1 TERMIO(7I)                      Ioctl Requests                      TERMIO(7I)
   3 NAME
   4      termio - general terminal interface
   7      #include <termio.h>
   9      ioctl(int fildes, int request, struct termio *arg);
  11      ioctl(int fildes, int request, int arg);
  13      #include <termios.h>
  15      ioctl(int fildes, int request, struct termios *arg);
  18      This release supports a general interface for asynchronous communications
  19      ports that is hardware-independent.  The user interface to this
  20      functionality is using function calls (the preferred interface) described
  21      in termios(3C) or ioctl() commands described in this section.  This
  22      section also discusses the common features of the terminal subsystem
  23      which are relevant with both user interfaces.
  25      When a terminal file is opened, it normally causes the process to wait
  26      until a connection is established.  In practice, user programs seldom
  27      open terminal files; they are opened by the system and become a user's
  28      standard input, output, and error files.  The first terminal file opened
  29      by the session leader that is not already associated with a session
  30      becomes the controlling terminal for that session.  The controlling
  31      terminal plays a special role in handling quit and interrupt signals, as
  32      discussed below.  The controlling terminal is inherited by a child
  33      process during a fork(2).  A process can break this association by
  34      changing its session using setsid(2).
  36      A terminal associated with one of these files ordinarily operates in
  37      full-duplex mode.  Characters may be typed at any time, even while output
  38      is occurring, and are only lost when the character input buffers of the
  39      system become completely full, which is rare.  For example, the number of
  40      characters in the line discipline buffer may exceed {MAX_CANON} and
  41      IMAXBEL (see below) is not set, or the user may accumulate {MAX_INPUT}
  42      number of input characters that have not yet been read by some program.
  43      When the input limit is reached, all the characters saved in the buffer
  44      up to that point are thrown away without notice.
  46    Session Management (Job Control)
  47      A control terminal will distinguish one of the process groups in the
  48      session associated with it to be the foreground process group.  All other
  49      process groups in the session are designated as background process
  50      groups.  This foreground process group plays a special role in handling
  51      signal-generating input characters, as discussed below.  By default, when
  52      a controlling terminal is allocated, the controlling process's process
  53      group is assigned as foreground process group.
  55      Background process groups in the controlling process's session are
  56      subject to a job control line discipline when they attempt to access
  57      their controlling terminal.  Process groups can be sent signals that will
  58      cause them to stop, unless they have made other arrangements.  An
  59      exception is made for members of orphaned process groups.
  61      An orphaned process group is one where the process group (see getpgid(2))
  62      has no members with a parent in a different process group but sharing the
  63      same controlling terminal.  When a member of an orphaned process group
  64      attempts to access its controlling terminal, EIO is returned because
  65      there would be no way to restart the process if it were stopped on one of
  66      these signals.
  68      If a member of a background process group attempts to read its
  69      controlling terminal, its process group will be sent a SIGTTIN signal,
  70      which will normally cause the members of that process group to stop.  If,
  71      however, the process is ignoring or holding SIGTTIN, or is a member of an
  72      orphaned process group, the read will fail with errno set to EIO, and no
  73      signal is sent.
  75      If a member of a background process group attempts to write its
  76      controlling terminal and the TOSTOP bit is set in the c_lflag field, its
  77      process group is sent a SIGTTOU signal, which will normally cause the
  78      members of that process group to stop.  If, however, the process is
  79      ignoring or holding SIGTTOU, the write will succeed.  If the process is
  80      not ignoring or holding SIGTTOU and is a member of an orphaned process
  81      group, the write will fail with errno set to EIO, and no signal will be
  82      sent.
  84      If TOSTOP is set and a member of a background process group attempts to
  85      ioctl() its controlling terminal, and that ioctl() will modify terminal
  86      parameters (for example, TCSETA, TCSETAW, TCSETAF, or TIOCSPGRP), its
  87      process group will be sent a SIGTTOU signal, which will normally cause
  88      the members of that process group to stop.  If, however, the process is
  89      ignoring or holding SIGTTOU, the ioctl will succeed.  If the process is
  90      not ignoring or holding SIGTTOU and is a member of an orphaned process
  91      group, the write will fail with errno set to EIO, and no signal will be
  92      sent.
  94    Canonical Mode Input Processing
  95      Normally, terminal input is processed in units of lines.  A line is
  96      delimited by a newline (ASCII LF) character, an end-of-file (ASCII EOT)
  97      character, or an end-of-line character.  This means that a program
  98      attempting to read will block until an entire line has been typed.  Also,
  99      no matter how many characters are requested in the read call, at most one
 100      line will be returned.  It is not necessary, however, to read a whole
 101      line at once; any number of characters may be requested in a read, even
 102      one, without losing information.
 104      During input, erase, erase2, and kill processing is normally done.  The
 105      ERASE and ERASE2 character (by default, the character DEL for ERASE and
 106      Control-h for ERASE2) erases the last character typed.  The WERASE
 107      character (the character Control-w) erases the last "word" typed in the
 108      current input line (but not any preceding spaces or tabs).  A "word" is
 109      defined as a sequence of non-blank characters, with tabs counted as
 110      blanks.  None of ERASE or ERASE2 or WERASE will erase beyond the
 111      beginning of the line.  The KILL character (by default, the character
 112      NAK) kills (deletes) the entire input line, and optionally outputs a
 113      newline character.  All these characters operate on a key stroke basis,
 114      independent of any backspacing or tabbing that may have been done.  The
 115      REPRINT character (the character Control-r) prints a newline followed by
 116      all characters that have not been read.  Reprinting also occurs
 117      automatically if characters that would normally be erased from the screen
 118      are fouled by program output.  The characters are reprinted as if they
 119      were being echoed; consequently, if ECHO is not set, they are not
 120      printed.
 122      The ERASE, ERASE2, and KILL characters may be entered literally by
 123      preceding them with the escape character.  In this case, the escape
 124      character is not read.  The erase, erase2, and kill characters may be
 125      changed.
 127    Non-canonical Mode Input Processing
 128      In non-canonical mode input processing, input characters are not
 129      assembled into lines, and erase and kill processing does not occur.  The
 130      MIN and TIME values are used to determine how to process the characters
 131      received.
 133      MIN represents the minimum number of characters that should be received
 134      when the read is satisfied (that is, when the characters are returned to
 135      the user).  TIME is a timer of 0.10-second granularity that is used to
 136      timeout bursty and short-term data transmissions.  The four possible
 137      values for MIN and TIME and their interactions are described below.
 139      Case A: MIN > 0, TIME > 0    In this case, TIME serves as an intercharacter
 140                                 timer and is activated after the first
 141                                 character is received.  Since it is an
 142                                 intercharacter timer, it is reset after a
 143                                 character is received.  The interaction
 144                                 between MIN and TIME is as follows: as soon as
 145                                 one character is received, the intercharacter
 146                                 timer is started.  If MIN characters are
 147                                 received before the intercharacter timer
 148                                 expires (note that the timer is reset upon
 149                                 receipt of each character), the read is
 150                                 satisfied.  If the timer expires before MIN
 151                                 characters are received, the characters
 152                                 received to that point are returned to the
 153                                 user.  Note that if TIME expires, at least one
 154                                 character will be returned because the timer
 155                                 would not have been enabled unless a character
 156                                 was received.  In this case (MIN > 0, TIME >
 157                                 0), the read sleeps until the MIN and TIME
 158                                 mechanisms are activated by the receipt of the
 159                                 first character.  If the number of characters
 160                                 read is less than the number of characters
 161                                 available, the timer is not reactivated and
 162                                 the subsequent read is satisfied immediately.
 164      Case B: MIN > 0, TIME = 0       In this case, since the value of TIME is zero,
 165                                 the timer plays no role and only MIN is
 166                                 significant.  A pending read is not satisfied
 167                                 until MIN characters are received (the pending
 168                                 read sleeps until MIN characters are
 169                                 received).  A program that uses this case to
 170                                 read record based terminal I/O may block
 171                                 indefinitely in the read operation.
 173      Case C: MIN = 0, TIME > 0       In this case, since MIN 0, TIME no longer
 174                                 represents an intercharacter timer: it now
 175                                 serves as a read timer that is activated as
 176                                 soon as a read(2) is done.  A read is
 177                                 satisfied as soon as a single character is
 178                                 received or the read timer expires.  Note
 179                                 that, in this case, if the timer expires, no
 180                                 character is returned.  If the timer does not
 181                                 expire, the only way the read can be satisfied
 182                                 is if a character is received.  In this case,
 183                                 the read will not block indefinitely waiting
 184                                 for a character; if no character is received
 185                                 within TIME *.10 seconds after the read is
 186                                 initiated, the read returns with zero
 187                                 characters.
 189      Case D: MIN = 0, TIME = 0  In this case, return is immediate.  The
 190                                 minimum of either the number of characters
 191                                 requested or the number of characters
 192                                 currently available is returned without
 193                                 waiting for more characters to be input.
 195    Comparing Different Cases of MIN, TIME Interaction
 196      Some points to note about MIN and TIME:
 198        o   In the following explanations, note that the interactions of MIN
 199            and TIME are not symmetric.  For example, when MIN >      0 and TIME =
 200            0, TIME has no effect.  However, in the opposite case, where MIN =
 201            0 and TIME >      0, both MIN and TIME play a role in that MIN is
 202            satisfied with the receipt of a single character.
 204        o   Also note that in case A (MIN > 0, TIME > 0), TIME represents an
 205            intercharacter timer, whereas in case C (MIN = 0, TIME > 0),      TIME
 206            represents a read timer.
 208      These two points highlight the dual purpose of the MIN/TIME feature.
 209      Cases A and B, where MIN >      0, exist to handle burst mode activity (for
 210      example, file transfer programs), where a program would like to process
 211      at least MIN characters at a time.  In case A, the intercharacter timer
 212      is activated by a user as a safety measure; in case B, the timer is
 213      turned off.
 215      Cases C and D exist to handle single character, timed transfers.  These
 216      cases are readily adaptable to screen-based applications that need to
 217      know if a character is present in the input queue before refreshing the
 218      screen.  In case C, the read is timed, whereas in case D, it is not.
 220      Another important note is that MIN is always just a minimum.  It does not
 221      denote a record length.  For example, if a program does a read of 20
 222      bytes, MIN is 10, and 25 characters are present, then 20 characters will
 223      be returned to the user.
 225    Writing Characters
 226      When one or more characters are written, they are transmitted to the
 227      terminal as soon as previously written characters have finished typing.
 228      Input characters are echoed as they are typed if echoing has been
 229      enabled.  If a process produces characters more rapidly than they can be
 230      typed, it will be suspended when its output queue exceeds some limit.
 231      When the queue is drained down to some threshold, the program is resumed.
 233    Special Characters
 234      Certain characters have special functions on input.  These functions and
 235      their default character values are summarized as follows:
 237      INTR     (Control-c or ASCII ETX) generates a SIGINT signal.  SIGINT is
 238               sent to all foreground processes associated with the controlling
 239               terminal.  Normally, each such process is forced to terminate,
 240               but arrangements may be made either to ignore the signal or to
 241               receive a trap to an agreed upon location.  (See
 242               signal.h(3HEAD)).
 244      QUIT     (Control-| or ASCII FS) generates a SIGQUIT signal.  Its
 245               treatment is identical to the interrupt signal except that,
 246               unless a receiving process has made other arrangements, it will
 247               not only be terminated but a core image file (called core) will
 248               be created in the current working directory.
 250      ERASE    (DEL) erases the preceding character.  It does not erase beyond
 251               the start of a line, as delimited by a NL, EOF, EOL, or EOL2
 252               character.
 254      ERASE2   (Control-h or ASCII BS) erases the preceding character, with
 255               behaviour identical to that of ERASE.
 257      WERASE   (Control-w or ASCII ETX) erases the preceding "word".  It does
 258               not erase beyond the start of a line, as delimited by a NL, EOF,
 259               EOL, or EOL2 character.
 261      KILL     (Control-u or ASCII NAK) deletes the entire line, as delimited
 262               by a NL, EOF, EOL, or EOL2 character.
 264      REPRINT  (Control-r or ASCII DC2) reprints all characters, preceded by a
 265               newline, that have not been read.
 267      EOF      (Control-d or ASCII EOT) may be used to generate an end-of-file
 268               from a terminal.  When received, all the characters waiting to
 269               be read are immediately passed to the program, without waiting
 270               for a newline, and the EOF is discarded.  Thus, if no characters
 271               are waiting (that is, the EOF occurred at the beginning of a
 272               line) zero characters are passed back, which is the standard
 273               end-of-file indication.  Unless escaped, the EOF character is
 274               not echoed.  Because EOT is the default EOF character, this
 275               prevents terminals that respond to EOT from hanging up.
 277      NL       (ASCII LF) is the normal line delimiter.  It cannot be changed
 278               or escaped.
 280      EOL      (ASCII NULL) is an additional line delimiter, like NL.  It is
 281               not normally used.
 283      EOL2     is another additional line delimiter.
 285      SWTCH    (Control-z or ASCII EM) Header file symbols related to this
 286               special character are present for compatibility purposes only
 287               and the kernel takes no special action on matching SWTCH (except
 288               to discard the character).
 290      SUSP     (Control-z or ASCII SUB) generates a SIGTSTP signal.  SIGTSTP
 291               stops all processes in the foreground process group for that
 292               terminal.
 294      DSUSP    (Control-y or ASCII EM).  It generates a SIGTSTP signal as SUSP
 295               does, but the signal is sent when a process in the foreground
 296               process group attempts to read the DSUSP character, rather than
 297               when it is typed.
 299      STOP     (Control-s or ASCII DC3) can be used to suspend output
 300               temporarily.  It is useful with CRT terminals to prevent output
 301               from disappearing before it can be read.  While output is
 302               suspended, STOP characters are ignored and not read.
 304      START    (Control-q or ASCII DC1) is used to resume output.  Output has
 305               been suspended by a STOP character.  While output is not
 306               suspended, START characters are ignored and not read.
 308      DISCARD  (Control-o or ASCII SI) causes subsequent output to be
 309               discarded.  Output is discarded until another DISCARD character
 310               is typed, more input arrives, or the condition is cleared by a
 311               program.
 313      STATUS   (Control-t or ASCII DC4) generates a SIGINFO signal.  Processes
 314               with a handler will output status information when they receive
 315               SIGINFO, for example, dd(1M).  If a process does not have a
 316               SIGINFO handler, the signal will be ignored.
 318      LNEXT    (Control-v or ASCII SYN) causes the special meaning of the next
 319               character to be ignored.  This works for all the special
 320               characters mentioned above.  It allows characters to be input
 321               that would otherwise be interpreted by the system (for example
 322               KILL, QUIT).  The character values for INTR, QUIT, ERASE,
 324               DSUSP, STOP, START, DISCARD, STATUS, and LNEXT may be changed to
 325               suit individual tastes.  If the value of a special control
 326               character is _POSIX_VDISABLE (0), the function of that special
 327               control character is disabled.  The ERASE, ERASE2, KILL, and EOF
 328               characters may be escaped by a preceding backslash (\)
 329               character, in which case no special function is done.  Any of
 330               the special characters may be preceded by the LNEXT character,
 331               in which case no special function is done.
 333    Modem Disconnect
 334      When a modem disconnect is detected, a SIGHUP signal is sent to the
 335      terminal's controlling process.  Unless other arrangements have been
 336      made, these signals cause the process to terminate.  If SIGHUP is ignored
 337      or caught, any subsequent read returns with an end-of-file indication
 338      until the terminal is closed.
 340      If the controlling process is not in the foreground process group of the
 341      terminal, a SIGTSTP is sent to the terminal's foreground process group.
 342      Unless other arrangements have been made, these signals cause the
 343      processes to stop.
 345      Processes in background process groups that attempt to access the
 346      controlling terminal after modem disconnect while the terminal is still
 347      allocated to the session will receive appropriate SIGTTOU and SIGTTIN
 348      signals.  Unless other arrangements have been made, this signal causes
 349      the processes to stop.
 351      The controlling terminal will remain in this state until it is
 352      reinitialized with a successful open by the controlling process, or
 353      deallocated by the controlling process.
 355    Terminal Parameters
 356      The parameters that control the behavior of devices and modules providing
 357      the termios interface are specified by the termios structure defined by
 358      <termios.h>.  Several ioctl(2) system calls that fetch or change these
 359      parameters use this structure that contains the following members:
 361        tcflag_t        c_iflag;        /* input modes */
 362        tcflag_t        c_oflag;        /* output modes */
 363        tcflag_t        c_cflag;        /* control modes */
 364        tcflag_t        c_lflag;        /* local modes */
 365        cc_t            c_cc[NCCS];     /* control chars */
 367      The special control characters are defined by the array c_cc.  The
 368      symbolic name NCCS is the size of the Control-character array and is also
 369      defined by <termios.h>.  The relative positions, subscript   names, and
 370      typical default values for each function are as follows:
 372      Relative Position    Subscript Name    Typical Default Value
 373      0                    VINTR             ETX
 374      1                    VQUIT             FS
 375      2                    VERASE            DEL
 376      3                    VKILL             NAK
 377      4                    VEOF              EOT
 378      5                    VEOL              NUL
 379      6                    VEOL2             NUL
 380      7                    VWSTCH            NUL
 381      8                    VSTART            NUL
 382      9                    VSTOP             DC3
 383      10                   VSUSP             SUB
 384      11                   VDSUSP            EM
 385      12                   VREPRINT          DC2
 386      13                   VDISCARD          SI
 387      14                   VWERASE           ETB
 388      15                   VLNEXT            SYN
 389      16                   VSTATUS           DC4
 390      17                   VERASE2           BS
 391      18-19                Reserved
 393    Input Modes
 394      The c_iflag field describes the basic terminal input control:
 396        IGNBRK   Ignore break condition.
 397        BRKINT   Signal interrupt on break.
 398        IGNPAR   Ignore characters with parity errors.
 399        PARMRK   Mark parity errors.
 400        INPCK    Enable input parity check.
 401        ISTRIP   Strip character.
 402        INLCR    Map NL to CR on input.
 403        IGNCR    Ignore CR.
 404        ICRNL    Map CR to NL on input.
 405        IUCLC    Map upper-case to lower-case on input.
 406        IXON     Enable start/stop output control.
 407        IXANY    Enable any character to restart output.
 408        IXOFF    Enable start/stop input control.
 409        IMAXBEL  Echo BEL on input line too long.
 411      If IGNBRK is set, a break condition (a character framing error with data
 412      all zeros) detected on input is ignored, that is, not put on the input
 413      queue and therefore not read by any process.  If IGNBRK is not set and
 414      BRKINT is set, the break condition shall flush the input and output
 415      queues and if the terminal is the controlling terminal of a foreground
 416      process group, the break condition generates a single SIGINT signal to
 417      that foreground process group.  If neither IGNBRK nor BRKINT is set, a
 418      break condition is read as a single `\0' (ASCII NULL) character, or if
 419      PARMRK is set, as `\377', `\0', c, where `\377' is a single character
 420      with value 377 octal (0xff hex, 255 decimal), `\0' is a single character
 421      with value 0, and c is the errored character received.
 423      If IGNPAR is set, a byte with framing or parity errors (other than break)
 424      is ignored.
 426      If PARMRK is set, and IGNPAR is not set, a byte with a framing or parity
 427      error (other than break) is given to the application as the three-
 428      character sequence: `\377', `\0', c, where `\377' is a single character
 429      with value 377 octal (0xff hex, 255 decimal), `\0' is a single character
 430      with value 0, and c is the errored character received.  To avoid
 431      ambiguity in this case, if ISTRIP is not set, a valid character of `\377'
 432      is given to the application as `\377'.  If neither IGNPAR nor PARMRK is
 433      set, a framing or parity error (other than break) is given to the
 434      application as a single `\0' (ASCII NULL) character.
 436      If INPCK is set, input parity checking is enabled.  If INPCK is not set,
 437      input parity checking is disabled.  This allows output parity generation
 438      without input parity errors.  Note that whether input parity checking is
 439      enabled or disabled is independent of whether parity detection is enabled
 440      or disabled.  If parity detection is enabled but input parity checking is
 441      disabled, the hardware to which the terminal is connected will recognize
 442      the parity bit, but the terminal special file will not check whether this
 443      is set correctly or not.
 445      If ISTRIP is set, valid input characters are first stripped to seven
 446      bits, otherwise all eight bits are processed.
 448      If INLCR is set, a received NL character is translated into a CR
 449      character.  If IGNCR is set, a received CR character is ignored (not
 450      read).  Otherwise, if ICRNL is set, a received CR character is translated
 451      into a NL character.
 453      If IUCLC is set, a received upper case, alphabetic character is
 454      translated into the corresponding lower case character.
 456      If IXON is set, start/stop output control is enabled.  A received STOP
 457      character suspends output and a received START character restarts output.
 458      The STOP and START characters will not be read, but will merely perform
 459      flow control functions.  If IXANY is set, any input character restarts
 460      output that has been suspended.
 462      If IXOFF is set, the system transmits a STOP character when the input
 463      queue is nearly full, and a START character when enough input has been
 464      read so that the input queue is nearly empty again.
 466      If IMAXBEL is set, the ASCII BEL character is echoed if the input stream
 467      overflows.  Further input is not stored, but any input already present in
 468      the input stream is not disturbed.  If IMAXBEL is not set, no BEL
 469      character is echoed, and all input present in the input queue is
 470      discarded if the input stream overflows.
 472    Output Modes
 473      The c_oflag field specifies the system treatment of output:
 475        OPOST   Post-process output.
 476        OLCUC   Map lower case to upper on output.
 477        ONLCR   Map NL to CR-NL on output.
 478        OCRNL   Map CR to NL on output.
 479        ONOCR   No CR output at column 0.
 480        ONLRET  NL performs CR function.
 481        OFILL   Use fill characters for delay.
 482        OFDEL   Fill is DEL, else INULL.
 483        NLDLY   Select newline delays:
 484                  NL0
 485                  NL1
 486        CRDLY   Select carriage-return delays:
 487                  CR0
 488                  CR1
 489                  CR2
 490                  CR3
 491        TABDLY  Select horizontal tab delays or tab expansion:
 492                  TAB0
 493                  TAB1
 494                  TAB2
 495                  TAB3   Expand tabs to spaces
 496                  XTABS  Expand tabs to spaces
 497        BSDLY   Select backspace delays:
 498                  BS0
 499                  BS1
 500        VTDLY   Select vertical tab delays:
 501                  VT0
 502                  VT1
 503        FFDLY   Select form feed delays:
 504                  FF0
 505                  FF1
 507      If OPOST is set, output characters are post-processed as indicated by the
 508      remaining flags; otherwise, characters are transmitted without change.
 510      If OLCUC is set, a lower case alphabetic character is transmitted as the
 511      corresponding upper case character.  This function is often used in
 512      conjunction with IUCLC.
 514      If ONLCR is set, the NL character is transmitted as the CR-NL character
 515      pair.  If OCRNL is set, the CR character is transmitted as the NL
 516      character.  If ONOCR is set, no CR character is transmitted when at
 517      column 0 (first position).  If ONRET is set, the NL character is assumed
 518      to do the carriage-return function; the column pointer is set to 0 and
 519      the delays specified for CR are used.  Otherwise, the NL character is
 520      assumed to do just the line-feed function; the column pointer remains
 521      unchanged.  The column pointer is also set to 0 if the CR character is
 522      actually transmitted.
 524      The delay bits specify how long transmission stops to allow for
 525      mechanical or other movement when certain characters are sent to the
 526      terminal.  In all cases, a value of 0 indicates no delay.  If OFILL is
 527      set, fill characters are transmitted for delay instead of a timed delay.
 528      This is useful for high baud rate terminals that need only a minimal
 529      delay.  If OFDEL is set, the fill character is DEL; otherwise it is NULL.
 531      If a form-feed or vertical-tab delay is specified, it lasts for about 2
 532      seconds.
 534      Newline delay lasts about 0.10 seconds.  If ONLRET is set, the carriage-
 535      return delays are used instead of the newline delays.  If OFILL is set,
 536      two fill characters are transmitted.
 538      Carriage-return delay type 1 is dependent on the current column position,
 539      type 2 is about 0.10 seconds, and type 3 is about 0.15 seconds.  If OFILL
 540      is set, delay type 1 transmits two fill characters, and type 2 transmits
 541      four fill characters.
 543      Horizontal-tab delay type 1 is dependent on the current column position.
 544      Type 2 is about 0.10 seconds.  Type 3 specifies that tabs are to be
 545      expanded into spaces.  If OFILL is set, two fill characters are
 546      transmitted for any delay.
 548      Backspace delay lasts about 0.05 seconds.  If OFILL is set, one fill
 549      character is transmitted.
 551      The actual delays depend on line speed and system load.
 553    Control Modes
 554      The c_cflag field describes the hardware control of the terminal:
 556        CBAUD      Baud rate:
 557                   B0       Hang up
 558                   B50      50 baud
 559                   B75      75 baud
 560                   B110     110 baud
 561                   B134     134 baud
 562                   B150     150 baud
 563                   B200     200 baud
 564                   B300     300 baud
 565                   B600     600 baud
 566                   B1200    1200 baud
 567                   B1800    1800 baud
 568                   B2400    2400 baud
 569                   B4800    4800 baud
 570                   B9600    9600 baud
 571                   B19200   19200 baud
 572                   EXTA     External A
 573                   B38400   38400 baud
 574                   EXTB     External B
 575                   B57600   57600 baud
 576                   B76800   76800 baud
 577                   B115200  115200 baud
 578                   B153600  153600 baud
 579                   B230400  230400 baud
 580                   B307200  307200 baud
 581                   B460800  460800 baud
 583        CSIZE      Character size:
 584                   CS5        5 bits
 585                   CS6        6 bits
 586                   CS7        7 bits
 587                   CS8        8 bits
 588                   CSTOPB     Send two stop bits, else one
 589                   CREAD      Enable receiver
 590                   PARENB     Parity enable
 591                   PARODD     Odd parity, else even
 592                   HUPCL      Hang up on last close
 593                   CLOCAL     Local line, else dial-up
 594                   CIBAUD     Input baud rate, if different from output rate
 595                   PAREXT     Extended parity for mark and space parity
 596                   CRTSXOFF   Enable inbound hardware flow control
 597                   CRTSCTS    Enable outbound hardware flow control
 598                   CBAUDEXT   Bit to indicate output speed > B38400
 599                   CIBAUDEXT  Bit to indicate input speed > B38400
 601      The CBAUD bits together with the CBAUDEXT bit specify the output baud
 602      rate.  To retrieve the output speed from the termios structure pointed to
 603      by termios_p see the following code segment.
 605        speed_t ospeed;
 606        if (termios_p->c_cflag &  CBAUDEXT)
 607         ospeed = (termios_p->c_cflag & CBAUD) +  CBAUD + 1;
 608        else
 609         ospeed = termios_p->c_cflag & CBAUD;
 611      To store the output speed in the termios structure pointed to by
 612      termios_p see the following code segment.
 614        speed_t ospeed;
 615        if (ospeed > CBAUD) {
 616         termios_p->c_cflag |= CBAUDEXT;
 617         ospeed -= (CBAUD + 1);
 618        } else {
 619         termios_p->c_cflag &= ~CBAUDEXT;
 620        }
 621        termios_p->c_cflag =
 622          (termios_p->c_cflag & ~CBAUD) | (ospeed & CBAUD);
 624      The zero baud rate, B0, is used to hang up the connection.  If B0 is
 625      specified, the data-terminal-ready signal is not asserted.  Normally,
 626      this disconnects the line.
 628      If the CIBAUDEXT or CIBAUD bits are not zero, they specify the input baud
 629      rate, with the CBAUDEXT and CBAUD bits specifying the output baud rate;
 630      otherwise, the output and input baud rates are both specified by the
 631      CBAUDEXT and CBAUD bits.  The values for the CIBAUD bits are the same as
 632      the values for the CBAUD bits, shifted left IBSHIFT bits.  For any
 633      particular hardware, impossible speed changes are ignored.  To retrieve
 634      the input speed in the termios structure pointed to by termios_p see the
 635      following code segment.
 637        speed_t ispeed;
 638        if (termios_p->c_cflag &  CIBAUDEXT) {
 639         ispeed = ((termios_p->c_cflag &  CIBAUD) >> IBSHIFT)
 640         + (CIBAUD >> IBSHIFT) +   1;
 641        } else {
 642         ispeed = (termios_p->c_cflag & CIBAUD) >> IBSHIFT;
 643        }
 645      To store the input speed in the termios structure pointed to by termios_p
 646      see the following code segment.
 648        speed_t ispeed;
 649        if (ispeed == 0) {
 650         ispeed = termios_p->c_cflag & CBAUD;
 651         if (termios_p->c_cflag & CBAUDEXT)
 652             ispeed += (CBAUD + 1);
 653        }
 654        if ((ispeed << IBSHIFT) > CIBAUD) {
 655          termios_p->c_cflag |= CIBAUDEXT;
 656          ispeed -= ((CIBAUD >> IBSHIFT)   + 1);
 657        } else {
 658          termios_p->c_cflag &= ~CIBAUDEXT;
 659        }
 660        termios_p->c_cflag =
 661          (termios_p->c_cflag & ~CIBAUD)  | ((ispeed << IBSHIFT) & CIBAUD);
 663      The CSIZE bits specify the character size in bits for both transmission
 664      and reception.  This size does not include the parity bit, if any.  If
 665      CSTOPB is set, two stop bits are used; otherwise, one stop bit is used.
 666      For example, at 110 baud, two stops bits are required.
 668      If PARENB is set, parity generation and detection is enabled, and a
 669      parity bit is added to each character.  If parity is enabled, the PARODD
 670      flag specifies odd parity if set; otherwise, even parity is used.
 672      If CREAD is set, the receiver is enabled.  Otherwise, no characters are
 673      received.
 675      If HUPCL is set, the line is disconnected when the last process with the
 676      line open closes it or terminates.  That is, the data-terminal-ready
 677      signal is not asserted.
 679      If CLOCAL is set, the line is assumed to be a local, direct connection
 680      with no modem control; otherwise, modem control is assumed.
 682      If CRTSXOFF is set, inbound hardware flow control is enabled.
 684      If CRTSCTS is set, outbound hardware flow control is enabled.
 686      The four possible combinations for the state of CRTSCTS and CRTSXOFF bits
 687      and their interactions are described below.
 689      Case A:  CRTSCTS off, CRTSXOFF off.  In this case the hardware flow
 690               control is disabled.
 692      Case B:  CRTSCTS on, CRTSXOFF off.  In this case only outbound hardware
 693               flow control is enabled.  The state of CTS signal is used to do
 694               outbound flow control.  It is expected that output will be
 695               suspended if CTS is low and resumed when CTS is high.
 697      Case C:  CRTSCTS off, CRTSXOFF on.  In this case only inbound hardware
 698               flow control is enabled.  The state of RTS signal is used to do
 699               inbound flow control.  It is expected that input will be
 700               suspended if RTS is low and resumed when RTS is high.
 702      Case D:  CRTSCTS on, CRTSXOFF on.  In this case both inbound and outbound
 703               hardware flow control are enabled.  Uses the state of CTS signal
 704               to do outbound flow control and RTS signal to do inbound flow
 705               control.
 707    Local Modes
 708      The c_lflag field of the argument structure is used by the line
 709      discipline to control terminal functions.  The basic line discipline
 710      provides the following:
 712        ISIG     Enable signals.
 713        ICANON   Canonical input (erase and kill processing).
 714        XCASE    Canonical upper/lower presentation.
 715        ECHO     Enable echo.
 716        ECHOE    Echo erase character as BS-SP-BS &.
 717        ECHOK    Echo NL after kill character.
 718        ECHONL   Echo NL.
 719        NOFLSH   Disable flush after interrupt or quit.
 720        TOSTOP   Send
 721        SIGTTOU  for background output.
 722        ECHOCTL  Echo control characters as char, delete as ^?.
 723        ECHOPRT  Echo erase character as character erased.
 724        ECHOKE   BS-SP-BS erase entire line on line kill.
 725        FLUSHO   Output is being flushed.
 726        PENDIN   Retype pending input at next read or input character.
 727        IEXTEN   Enable extended (implementation-defined) functions.
 729      If ISIG is set, each input character is checked against the special
 730      control characters INTR, QUIT, SWTCH, SUSP, STATUS, and DSUSP.  If an
 731      input character matches one of these control characters, the function
 732      associated with that character is performed.  (Note: If SWTCH is set and
 733      the character matches, the character is simply discarded.  No other
 734      action is taken.) If ISIG is not set, no checking is done.  Thus, these
 735      special input functions are possible only if ISIG is set.
 737      If ICANON is set, canonical processing is enabled.  This enables the
 738      erase and kill edit functions, and the assembly of input characters into
 739      lines delimited by NL-c, EOF, EOL, and EOL.  If ICANON is not set, read
 740      requests are satisfied directly from the input queue.  A read is not
 741      satisfied until at least MIN characters have been received or the timeout
 742      value TIME has expired between characters.  This allows fast bursts of
 743      input to be read efficiently while still allowing single character input.
 744      The time value represents tenths of seconds.
 746      If XCASE is set and ICANON is set, an upper case letter is accepted on
 747      input if preceded by a backslash `\' character, and is output preceded by
 748      a backslash `\' character.  In this mode, the following escape sequences
 749      are generated on output and accepted on input:
 751        FOR:    USE:
 752        `       \'
 753        |       \!
 754        ~       \^
 755        {       \(
 756        }       \)
 757        \       \\
 759      For example, input A as \a, \n as \\n, and \N as \\\n.
 761      If ECHO is set, characters are echoed as received.
 763      When ICANON is set, the following echo functions are possible.
 765            o   If ECHO and ECHOE are set, and ECHOPRT is not set, the ERASE,
 766                ERASE2, and WERASE characters are echoed as one or more ASCII
 767                BS SP BS, which clears the last character(s) from a CRT screen.
 769            o   If ECHO, ECHOPRT, and IEXTEN are set, the first ERASE, ERASE2,
 770                and WERASE character in a sequence echoes as a backslash `\',
 771                followed by the characters being erased.  Subsequent ERASE and
 772                WERASE characters echo the characters being erased, in reverse
 773                order.  The next non-erase character causes a `/' (slash) to be
 774                typed before it is echoed.  ECHOPRT should be used for hard
 775                copy terminals.
 777            o   If ECHOKE and IEXTEN are set, the kill character is echoed by
 778                erasing each character on the line from the screen (using the
 779                mechanism selected by ECHOE and ECHOPR).
 781            o   If ECHOK is set, and ECHOKE is not set, the NL character is
 782                echoed after the kill character to emphasize that the line is
 783                deleted.  Note that a `\' (escape) character or an LNEXT
 784                character preceding the erase or kill character removes any
 785                special function.
 787            o   If ECHONL is set, the NL character is echoed even if ECHO is
 788                not set.  This is useful for terminals set to local echo (so
 789                called half-duplex).
 791      If ECHOCTL and IEXTEN are set, all control characters (characters with
 792      codes between 0 and 37 octal) other than ASCII TAB, ASCII NL, the START
 793      character, and the STOP character, ASCII CR, and ASCII BS are echoed as
 794      ^X, where X is the character given by adding `100' octal to the code of
 795      the control character (so that the character with octal code `1' is
 796      echoed as ^A), and the ASCII DEL character, with code `177' octal, is
 797      echoed as ^?.
 799      If NOFLSH is set, the normal flush of the input and output queues
 800      associated with the INTR, QUIT, STATUS, and SUSP characters is not done.
 801      This bit should be set when restarting system calls that read from or
 802      write to a terminal (see sigaction(2)).
 804      If TOSTOP and IEXTEN are set, the signal SIGTTOU is sent to a process
 805      that tries to write to its controlling terminal if it is not in the
 806      foreground process group for that terminal.  This signal normally stops
 807      the process.  Otherwise, the output generated by that process is output
 808      to the current output stream.  Processes that are blocking or ignoring
 809      SIGTTOU signals are excepted and allowed to produce output, if any.
 811      If FLUSHO and IEXTEN are set, data written to the terminal is discarded.
 812      This bit is set when the FLUSH character is typed.  A program can cancel
 813      the effect of typing the FLUSH character by clearing FLUSHO.
 815      If PENDIN and IEXTEN are set, any input that has not yet been read is
 816      reprinted when the next character arrives as input.  PENDIN is then
 817      automatically cleared.
 819      If IEXTEN is set, the following implementation-defined functions are
 820      enabled: special characters ( WERASE, REPRINT, DISCARD, and LNEXT) and
 821      local flags ( TOSTOP, ECHOCTL, ECHOPRT, ECHOKE, FLUSHO, and PENDIN).
 823    Minimum and Timeout
 824      The MIN and TIME values were described previously, in the subsection,
 825      Non-canonical Mode Input Processing.  The initial value of MIN is 1, and
 826      the initial value of TIME is 0.
 828    Terminal Size
 829      The number of lines and columns on the terminal's display is specified in
 830      the winsize structure defined by <sys/termios.h> and includes the
 831      following members:
 833        unsigned short  ws_row;        /* rows, in characters */
 834        unsigned short  ws_col;        /* columns, in characters */
 835        unsigned short  ws_xpixel;     /* horizontal size, in pixels */
 836        unsigned short  ws_ypixel;     /* vertical size, in pixels */
 838    Termio Structure
 839      The SunOS/SVR4 termio structure is used by some ioctl()s; it is defined
 840      by <sys/termio.h> and includes the   following members:
 842        unsigned        short   c_iflag;    /* input modes */
 843        unsigned        short   c_oflag;    /* output modes */
 844        unsigned        short   c_cflag;    /* control modes */
 845        unsigned        short   c_lflag;    /* local modes */
 846        char                    c_line;     /* line discipline */
 847        unsigned        char    c_cc[NCC];  /* control chars */
 849      The special control characters are defined by the array c_cc.  The
 850      symbolic name NCC is the size of the Control-character array and is also
 851      defined by <termio.h>.  The relative positions, subscript names, and
 852      typical default values for each function are as follows:
 854      Relative Positions    Subscript Names    Typical Default Values
 855      0                     VINTR              EXT
 856      1                     VQUIT              FS
 857      2                     VERASE             DEL
 858      3                     VKILL              NAK
 859      4                     VEOF               EOT
 860      5                     VEOL               NUL
 861      6                     VEOL2              NUL
 862      7                     Reserved
 864      The MIN values is stored in the VMIN element of the c_cc array; the TIME
 865      value is stored in the VTIME element of the c_cc array.  The VMIN element
 866      is the same element as the VEOF element; the VTIME element is the same
 867      element as the VEOL element.
 869      The calls that use the termio structure only affect the flags and control
 870      characters that can be stored in the termio structure; all other flags
 871      and control characters are unaffected.
 873    Modem Lines
 874      On special files representing serial ports, modem control lines can be
 875      read.  Control lines (if the underlying hardware supports it) may also be
 876      changed.  Status lines are read-only.  The following modem control and
 877      status lines may be supported by a device; they are defined by
 878      <sys/termios.h>:
 880        TIOCM_LE   line enable
 881        TIOCM_DTR  data terminal ready
 882        TIOCM_RTS  request to send
 883        TIOCM_ST   secondary transmit
 884        TIOCM_SR   secondary receive
 885        TIOCM_CTS  clear to send
 886        TIOCM_CAR  carrier detect
 887        TIOCM_RNG  ring
 888        TIOCM_DSR  data set ready
 890      TIOCM_CD is a synonym for TIOCM_CAR, and TIOCM_RI is a synonym for
 891      TIOCM_RNG.  Not all of these are necessarily supported by any particular
 892      device; check the manual page for the device in question.
 894      The software carrier mode can be enabled or disabled using the
 895      TIOCSSOFTCAR ioctl().  If the software carrier flag for a line is off,
 896      the line pays attention to the hardware carrier detect (DCD) signal.  The
 897      tty device associated with the line cannot be opened until DCD is
 898      asserted.  If the software carrier flag is on, the line behaves as if DCD
 899      is always asserted.
 901      The software carrier flag is usually turned on for locally connected
 902      terminals or other devices, and is off for lines with modems.
 904      To be able to issue the TIOCGSOFTCAR and TIOCSSOFTCAR ioctl() calls, the
 905      tty line should be opened with O_NDELAY so that the open(2) will not wait
 906      for the carrier.
 908    Default Values
 909      The initial termios values upon driver open is configurable.  This is
 910      accomplished by setting the "ttymodes" property in the file
 911      /kernel/drv/options.conf.  Since this property is assigned during system
 912      initialization, any change to the "ttymodes" property will not take
 913      effect until the next reboot.  The string value assigned to this property
 914      should be in the same format as the output of the stty(1) command with
 915      the -g option.
 917      If this property is undefined, the following termios modes are in effect.
 918      The initial input control value is BRKINT, ICRNL, IXON, IMAXBEL.  The
 919      initial output control value is OPOST, ONLCR, TAB3.  The initial hardware
 920      control value is B9600, CS8, CREAD.  The initial line-discipline control
 924      The ioctl()s supported by devices and STREAMS modules providing the
 925      termios(3C) interface are listed below.  Some calls may not be supported
 926      by all devices or modules.  The functionality provided by these calls is
 927      also available through the preferred function call interface specified on
 928      termios.
 930      TCGETS        The argument is a pointer to a termios structure.  The
 931                    current terminal parameters are fetched and stored into
 932                    that structure.
 934      TCSETS        The argument is a pointer to a termios structure.  The
 935                    current terminal parameters are set from the values stored
 936                    in that structure.  The change is immediate.
 938      TCSETSW       The argument is a pointer to a termios structure.  The
 939                    current terminal parameters are set from the values stored
 940                    in that structure.  The change occurs after all characters
 941                    queued for output have been transmitted.  This form should
 942                    be used when changing parameters that affect output.
 944      TCSETSF       The argument is a pointer to a termios structure.  The
 945                    current terminal parameters are set from the values stored
 946                    in that structure.  The change occurs after all characters
 947                    queued for output have been transmitted; all characters
 948                    queued for input are discarded and then the change occurs.
 950      TCGETA        The argument is a pointer to a termio structure.  The
 951                    current terminal parameters are fetched, and those
 952                    parameters that can be stored in a termio structure are
 953                    stored into that structure.
 955      TCSETA        The argument is a pointer to a termio structure.  Those
 956                    terminal parameters that can be stored in a termio
 957                    structure are set from the values stored in that structure.
 958                    The change is immediate.
 960      TCSETAW       The argument is a pointer to a termio structure.  Those
 961                    terminal parameters that can be stored in a termio
 962                    structure are set from the values stored in that structure.
 963                    The change occurs after all characters queued for output
 964                    have been transmitted.  This form should be used when
 965                    changing parameters that affect output.
 967      TCSETAF       The argument is a pointer to a termio structure.  Those
 968                    terminal parameters that can be stored in a termio
 969                    structure are set from the values stored in that structure.
 970                    The change occurs after all characters queued for output
 971                    have been transmitted; all characters queued for input are
 972                    discarded and then the change occurs.
 974      TCSBRK        The argument is an int value.  Wait for the output to
 975                    drain.  If the argument is 0, then send a break (zero
 976                    valued bits for 0.25 seconds).
 978      TCXONC        Start/stop control.  The argument is an int value.  If the
 979                    argument is 0, suspend output; if 1, restart suspended
 980                    output; if 2, suspend input; if 3, restart suspended input.
 982      TCFLSH        The argument is an int value.  If the argument is 0, flush
 983                    the input queue; if 1, flush the output queue; if 2, flush
 984                    both the input and output queues.
 986      TIOCGPGRP     The argument is a pointer to a pid_t.  Set the value of
 987                    that pid_t to the process group ID of the foreground
 988                    process group associated with the terminal.  See
 989                    termios(3C) for a description of TCGETPGRP.
 991      TIOCSPGRP     The argument is a pointer to a pid_t.  Associate the
 992                    process group whose process group ID is specified by the
 993                    value of that pid_t with the terminal.  The new process
 994                    group value must be in the range of valid process group ID
 995                    values.  Otherwise, the error EPERM is returned.
 997      TIOCGSID      The argument is a pointer to a pid_t.  The session ID of
 998                    the terminal is fetched and stored in the pid_t.
1000      TIOCGWINSZ    The argument is a pointer to a winsize structure.  The
1001                    terminal driver's notion of the terminal size is stored
1002                    into that structure.
1004      TIOCSWINSZ    The argument is a pointer to a winsize structure.  The
1005                    terminal driver's notion of the terminal size is set from
1006                    the values specified in that structure.  If the new sizes
1007                    are different from the old sizes, a SIGWINCH signal is set
1008                    to the process group of the terminal.
1010      TIOCMBIS      The argument is a pointer to an int whose value is a mask
1011                    containing modem control lines to be turned on.  The
1012                    control lines whose bits are set in the argument are turned
1013                    on; no other control lines are affected.
1015      TIOCMBIC      The argument is a pointer to an int whose value is a mask
1016                    containing modem control lines to be turned off.  The
1017                    control lines whose bits are set in the argument are turned
1018                    off; no other control lines are affected.
1020      TIOCMGET      The argument is a pointer to an int.  The current state of
1021                    the modem status lines is fetched and stored in the int
1022                    pointed to by the argument.
1024      TIOCMSET      The argument is a pointer to an int containing a new set of
1025                    modem control lines.  The modem control lines are turned on
1026                    or off, depending on whether the bit for that mode is set
1027                    or clear.
1029      TIOCSPPS      The argument is a pointer to an int that determines whether
1030                    pulse-per-second event handling is to be enabled (non-zero)
1031                    or disabled (zero).  If a one-pulse-per-second reference
1032                    clock is attached to the serial line's data carrier detect
1033                    input, the local system clock will be calibrated to it.  A
1034                    clock with a high error, that is, a deviation of more than
1035                    25 microseconds per tick, is ignored.
1037      TIOCGPPS      The argument is a pointer to an int, in which the state of
1038                    the even handling is returned.  The int is set to a non-
1039                    zero value if pulse-per-second (PPS) handling has been
1040                    enabled.  Otherwise, it is set to zero.
1042      TIOCGSOFTCAR  The argument is a pointer to an int whose value is 1 or 0,
1043                    depending on whether the software carrier detect is turned
1044                    on or off.
1046      TIOCSSOFTCAR  The argument is a pointer to an int whose value is 1 or 0.
1047                    The value of the integer should be 0 to turn off software
1048                    carrier, or 1 to turn it on.
1050      TIOCGPPSEV    The argument is a pointer to a struct ppsclockev.  This
1051                    structure contains the following members:
1053                      struct timeval tv;
1054                      uint32_t serial;
1056                    tv is the system clock timestamp when the event (pulse on
1057                    the DCD pin) occurred.  serial is the ordinal of the event,
1058                    which each consecutive event being assigned the next
1059                    ordinal.  The first event registered gets a serial value of
1060                    1.  The TIOCGPPSEV returns the last event registered;
1061                    multiple calls will persistently return the same event
1062                    until a new one is registered.  In addition to time
1063                    stamping and saving the event, if it is of one-second
1064                    period and of consistently high accuracy, the local system
1065                    clock will automatically calibrate to it.
1067 FILES
1068      Files in or under /dev
1071      stty(1), fork(2), getpgid(2), getsid(2), ioctl(2), setsid(2),
1072      sigaction(2), signal(3C), tcsetpgrp(3C), termios(3C), signal.h(3HEAD),
1073      streamio(7I)
1075 illumos                        February 17, 2020                       illumos