TTY(4)                                                     TTY(4)

     NAME
          tty - general terminal interface

     DESCRIPTION
          This section describes both a particular special file, and
          the general nature of the terminal interface.

          The file /dev/tty is, in each process, a synonym for the
          control terminal associated with that process.  It is useful
          for programs that wish to be sure of writing messages on the
          terminal no matter how output has been redirected.  It can
          also be used for programs that demand a file name for out-
          put, when typed output is desired and it is tiresome to find
          out which terminal is currently in use.

          As for terminals in general: all of the low-speed asyn-
          chronous communications ports use the same general inter-
          face, no matter what hardware is involved.  The remainder of
          this section discusses the common features of the interface.

          When a terminal file is opened, it causes the process to
          wait until a connection is established.  In practice user's
          programs seldom open these files; they are opened by init
          and become a user's input and output file.  The very first
          terminal file open in a process becomes the control terminal
          for that process.  The control terminal plays a special role
          in handling quit or interrupt signals, as discussed below.
          The control terminal is inherited by a child process during
          a fork, even if the control terminal is closed.  The set of
          processes that thus share a control terminal is called a
          process group; all members of a process group receive cer-
          tain signals together, see DEL below and kill(2).

          A terminal associated with one of these files ordinarily
          operates in full-duplex mode.  Characters may be typed at
          any time, even while output is occurring, and are only lost
          when the system's character input buffers become completely
          choked, which is rare, or when the user has accumulated the
          maximum allowed number of input characters that have not yet
          been read by some program.  Currently this limit is 256
          characters.  When the input limit is reached all the saved
          characters are thrown away without notice.

          Normally, terminal input is processed in units of lines.
          This means that a program attempting to read will be sus-
          pended until an entire line has been typed.  Also, no matter
          how many characters are requested in the read call, at most
          one line will be returned.  It is not however necessary to
          read a whole line at once; any number of characters may be
          requested in a read, even one, without losing information.

     TTY(4)                                                     TTY(4)

          There are special modes, discussed below, that permit the
          program to read each character as typed without waiting for
          a full line.

          During input, erase and kill processing is normally done.
          By default, the character `#' erases the last character
          typed, except that it will not erase beyond the beginning of
          a line or an EOT.  By default, the character `@' kills the
          entire line up to the point where it was typed, but not
          beyond an EOT.  Both these characters operate on a keystroke
          basis independently of any backspacing or tabbing that may
          have been done.  Either `@' or `#' may be entered literally
          by preceding it by `\'; the erase or kill character remains,
          but the `\' disappears.  These two characters may be changed
          to others.

          When desired, all upper-case letters are mapped into the
          corresponding lower-case letter.  The upper-case letter may
          be generated by preceding it by `\'.  In addition, the fol-
          lowing escape sequences can be generated on output and
          accepted on input:

          for  use
          `    \'
          |    \!
          ~    \^
          {    \(
          }    \)

          Certain ASCII control characters have special meaning.
          These characters are not passed to a reading program except
          in raw mode where they lose their special character.  Also,
          it is possible to change these characters from the default;
          see below.

          EOT  (Control-D) may be used to generate an end of file from
               a terminal.  When an EOT is received, all the charac-
               ters waiting to be read are immediately passed to the
               program, without waiting for a new-line, and the EOT is
               discarded.  Thus if there are no characters waiting,
               which is to say the EOT occurred at the beginning of a
               line, zero characters will be passed back, and this is
               the standard end-of-file indication.

          DEL  (Rubout) is not passed to a program but generates an
               interrupt signal which is sent to all processes with
               the associated control terminal.  Normally each such
               process is forced to terminate, but arrangements may be
               made either to ignore the signal or to receive a trap
               to an agreed-upon location.  See signal(2).

          FS   (Control-\ or control-shift-L) generates the quit

     TTY(4)                                                     TTY(4)

               signal.  Its treatment is identical to the interrupt
               signal except that unless a receiving process has made
               other arrangements it will not only be terminated but a
               core image file will be generated.

          DC3  (Control-S) delays all printing on the terminal until
               something is typed in.

          DC1  (Control-Q) restarts  printing after DC3 without gener-
               ating any input to a program.

          When the carrier signal from the dataset drops (usually
          because the user has hung up his terminal) a hangup signal
          is sent to all processes with the terminal as control termi-
          nal.  Unless other arrangements have been made, this signal
          causes the processes to terminate.  If the hangup signal is
          ignored, any read returns with an end-of-file indication.
          Thus programs that read a terminal and test for end-of-file
          on their input can terminate appropriately when hung up on.

          When one or more characters are written, they are actually
          transmitted to the terminal as soon as previously-written
          characters have finished typing.  Input characters are
          echoed by putting them in the output queue as they arrive.
          When a process produces characters more rapidly than they
          can be typed, it will be suspended when its output queue
          exceeds some limit.  When the queue has drained down to some
          threshold the program is resumed.  Even parity is always
          generated on output.  The EOT character is not transmitted
          (except in raw mode) to prevent terminals that respond to it
          from hanging up.

          Several ioctl(2) calls apply to terminals.  Most of them use
          the following structure, defined in <sgtty.h>:

          struct sgttyb {
               char sg_ispeed;
               char sg_ospeed;
               char sg_erase;
               char sg_kill;
               int  sg_flags;
          };

          The sg_ispeed and sg_ospeed fields describe the input and
          output speeds of the device according to the following
          table, which corresponds to the DEC DH-11 interface.  If
          other hardware is used, impossible speed changes are
          ignored.  Symbolic values in the table are as defined in
          <sgtty.h>.

          B0      0    (hang up dataphone)
          B50     1    50 baud

     TTY(4)                                                     TTY(4)

          B75     2    75 baud
          B110    3    110 baud
          B134    4    134.5 baud
          B150    5    150 baud
          B200    6    200 baud
          B300    7    300 baud
          B600    8    600 baud
          B1200   9    1200 baud
          B1800   10   1800 baud
          B2400   11   2400 baud
          B4800   12   4800 baud
          B9600   13   9600 baud
          EXTA    14   External A
          EXTB    15   External B

          In the current configuration, only 110, 150, 300 and 1200
          baud are really supported on dial-up lines.  Code conversion
          and line control required for IBM 2741's (134.5 baud) must
          be implemented by the user's program.  The half-duplex line
          discipline required for the 202 dataset (1200 baud) is not
          supplied; full-duplex 212 datasets work fine.

          The sg_erase and sg_kill fields of the argument structure
          specify the erase and kill characters respectively.
          (Defaults are # and @.)

          The sg_flags field of the argument structure contains sev-
          eral bits that determine the system's treatment of the ter-
          minal:

          ALLDELAY 0177400 Delay algorithm selection
          BSDELAY  0100000 Select backspace delays (not implemented):
          BS0      0
          BS1      0100000
          VTDELAY  0040000 Select form-feed and vertical-tab delays:
          FF0      0
          FF1      0100000
          CRDELAY  0030000 Select carriage-return delays:
          CR0      0
          CR1      0010000
          CR2      0020000
          CR3      0030000
          TBDELAY  0006000 Select tab delays:
          TAB0     0
          TAB1     0001000
          TAB2     0004000
          XTABS    0006000
          NLDELAY  0001400 Select new-line delays:
          NL0      0
          NL1      0000400
          NL2      0001000
          NL3      0001400

     TTY(4)                                                     TTY(4)

          EVENP    0000200 Even parity allowed on input (most terminals)
          ODDP     0000100 Odd parity allowed on input
          RAW      0000040 Raw mode: wake up on all characters, 8-bit interface
          CRMOD    0000020 Map CR into LF; echo LF or CR as CR-LF
          ECHO     0000010 Echo (full duplex)
          LCASE    0000004 Map upper case to lower on input
          CBREAK   0000002 Return each character as soon as typed
          TANDEM   0000001 Automatic flow control

          The delay bits specify how long transmission stops to allow
          for mechanical or other movement when certain characters are
          sent to the terminal.  In all cases a value of 0 indicates
          no delay.

          Backspace delays are currently ignored but might be used for
          Terminet 300's.

          If a form-feed/vertical tab delay is specified, it lasts for
          about 2 seconds.

          Carriage-return delay type 1 lasts about .08 seconds and is
          suitable for the Terminet 300.  Delay type 2 lasts about .16
          seconds and is suitable for the VT05 and the TI 700.  Delay
          type 3 is unimplemented and is 0.

          New-line delay type 1 is dependent on the current column and
          is tuned for Teletype model 37's.  Type 2 is useful for the
          VT05 and is about .10 seconds.  Type 3 is unimplemented and
          is 0.

          Tab delay type 1 is dependent on the amount of movement and
          is tuned to the Teletype model 37.  Type 3, called XTABS, is
          not a delay at all but causes tabs to be replaced by the
          appropriate number of spaces on output.

          Characters with the wrong parity, as determined by bits 200
          and 100, are ignored.

          In raw mode, every character is passed immediately to the
          program without waiting until a full line has been typed.
          No erase or kill processing is done; the end-of-file indica-
          tor (EOT), the interrupt character (DEL) and the quit char-
          acter (FS) are not treated specially.  There are no delays
          and no echoing, and no replacement of one character for
          another; characters are a full 8 bits for both input and
          output (parity is up to the program).

          Mode 020 causes input carriage returns to be turned into
          new-lines; input of either CR or LF causes LF-CR both to be
          echoed (for terminals with a new-line function).

          CBREAK is a sort of half-cooked (rare?) mode.  Programs can

     TTY(4)                                                     TTY(4)

          read each character as soon as typed, instead of waiting for
          a full line, but quit and interrupt work, and output delays,
          case-translation, CRMOD, XTABS, ECHO, and parity work nor-
          mally.  On the other hand there is no erase or kill, and no
          special treatment of \ or EOT.

          TANDEM mode causes the system to produce a stop character
          (default DC3) whenever the input queue is in danger of over-
          flowing, and a start character (default DC1) when the input
          queue has drained sufficiently.  It is useful for flow con-
          trol when the `terminal' is actually another machine that
          obeys the conventions.

          Several ioctl calls have the form:

          #include <sgtty.h>

          ioctl(fildes, code, arg)
          struct sgttyb *arg;

          The applicable codes are:

          TIOCGETP
               Fetch the parameters associated with the terminal, and
               store in the pointed-to structure.

          TIOCSETP
               Set the parameters according to the pointed-to struc-
               ture.  The interface delays until output is quiescent,
               then throws away any unread characters, before changing
               the modes.

          TIOCSETN
               Set the parameters but do not delay or flush input.
               Switching out of RAW or CBREAK mode may cause some gar-
               bage input.

          With the following codes the arg is ignored.

          TIOCEXCL
               Set ``exclusive-use'' mode: no further opens are per-
               mitted until the file has been closed.

          TIOCNXCL
               Turn off ``exclusive-use'' mode.

          TIOCHPCL
               When the file is closed for the last time, hang up the
               terminal.  This is useful when the line is associated
               with an ACU used to place outgoing calls.

          TIOCFLUSH

     TTY(4)                                                     TTY(4)

               All characters waiting in input or output queues are
               flushed.

          The following codes affect characters that are special to
          the terminal interface.  The argument is a pointer to the
          following structure, defined in <sgtty.h>:

          struct tchars {
               char t_intrc;       /* interrupt */
               char t_quitc;       /* quit */
               char t_startc; /* start output */
               char t_stopc;  /* stop output */
               char t_eofc;        /* end-of-file */
               char t_brkc;        /* input delimiter (like nl) */
          };

          The default values for these characters are DEL, FS, DC1,
          DC3, EOT, and -1.  A character value of -1 eliminates the
          effect of that character.  The t_brkc character, by default
          -1, acts like a new-line in that it terminates a `line,' is
          echoed, and is passed to the program.  The `stop' and
          `start' characters may be the same, to produce a toggle
          effect.  It is probably counterproductive to make other spe-
          cial characters (including erase an kill) identical.

          The calls are:

          TIOCSETC
               Change the various special characters to those given in
               the structure.

          TIOCSETP
               Set the special characters to those given in the struc-
               ture.

     FILES
          /dev/tty
          /dev/tty*
          /dev/console

     SEE ALSO
          getty(8), stty (1), signal(2), ioctl(2)

     BUGS
          Half-duplex terminals are not supported.

          The terminal handler has clearly entered the race for ever-
          greater complexity and generality.  It's still not complex
          and general enough for TENEX fans.