TTY(4)                              Devices                             TTY(4)




NAME

       tty - general terminal interface


SYNOPSIS

       #include <sgtty.h>


DESCRIPTION

       This file documents the special file .tty and the terminal drivers used
       for user-oriented I/O.

       Terminals are controlled through calls to the ioctl(2) system call:

            #include <sgtty.h>

            ioctl(int filedes, unsigned long code, void *arg);

       This is a very flexible interface where filedes specifies the  terminal
       to  modify,  code  indicates  an action code, and arg is a pointer to a
       parameter block.  The type of variable pointed to by arg and how it  is
       interpreted depends on the value of code.

       Due  to  the colorful history of UNIX systems, the data structures used
       to manipulate terminal modes  and  settings  are  separated  into  five
       groups.  Future revisions of GNO will implement the POSIX termio inter-
       face, which consolidates these structures into one place.

       This manual page first explains the concepts of controlling  terminals,
       process  groups,  and  terminal modes.  It then goes on to explain each
       code that can be used with ioctl(2) to control a terminal.  Since there
       are  five data structures used in ioctl calls to control terminals, the
       description of the possible codes in this man page is  ordered  by  the
       type of the data structure pointed to by arg.

       The Controlling Terminal
              Every  process  has  associated  with it a controlling terminal,
              which is the terminal from which the process  was  invoked.   In
              some  versions  of UNIX, the controlling terminal association is
              responsible for job control; this is not so under GNO.   A  pro-
              cess'  controlling  terminal  is  inherited from its parent.  By
              opening the special file .tty, a process can access its control-
              ling  terminal.   This is useful where the input and output of a
              process was redirected and the process wants to be sure of  get-
              ting input from or output to the user at the terminal.

              A process can remove the association it has with its controlling
              terminal by opening the file .tty and issuing the system call:

                   ioctl (fd, TIOCNOTTY, NULL);

              where fd is the file descriptor associated with .tty.   This  is
              often desirable in server processes.

       Process Groups
              Every terminal has an associated process group.  Any time a sig-
              nal-generating special character is typed at the  terminal,  the
              terminal's  process group is sent that signal.  UNIX systems set
              process groups using ioctl(2) calls, but under GNO a new  inter-
              face  method  is  used; process group assignments are controlled
              with the JOBCONTROL(2) routines.

       Modes  There are three modes in which terminal drivers operate.   These
              modes control how the driver deals with I/O.

              cooked This  is  the  default mode of the terminal driver. If an
                     incoming character  is  one  of  the  special  characters
                     defined  in  sgttyb,  tchars, or ltchars, the appropriate
                     action is performed (see below).  This mode  also  allows
                     for  input  editing, as input is internally buffered line
                     by line, and data is returned to a reading  process  only
                     when CR is entered.

              cbreak Input  is  returned  on a per-character basis, instead of
                     line by line as in cooked mode. If no data is  available,
                     a read will block the calling process.  If data is avail-
                     able, a number of characters up to but not exceeding  the
                     requested  number  will  be  returned. Special characters
                     such as t_intrc are not handled, but are passed on to the
                     caller as data.

              raw    Like cbreak mode, except that no input or output process-
                     ing whatsoever is performed.

       struct sgttyb
              The basic ioctls use the sgttyb structure:

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


              sg_ispeed and sg_ospeed indicate the baud rates  for  input  and
              output  according to the following table.  Speed changes that do
              not apply to a particular piece of  hardware  are  ignored  (for
              instance,  the  console  driver does not access a serial port so
              all baud rate settings are, in effect, impossible).   Also,  not
              all  the baud rates supported by a particular device are allowed
              to be set from this interface.

              These symbolic names for the baud rate settings are  defined  in
              <sgtty.h>.

                     B0        0    (hang up dataphone)
                     B50       1    50 baud
                     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
                     B19200    14   19200 baud
                     EXTA      14   19200 baud
                     B38400    15   38400 baud
                     EXTB      15   38400 baud

              The  sg_erase  and sg_kill fields specify the line-editing erase
              and kill characters.  sg_erase is 0x7F (delete) by default,  and
              sg_kill is not currently used.

              sg_flags  is a bitmapped value that indicates various state set-
              tings for the terminal driver (values are in hex).

              EVENP     0x80 Use Even parity (serial devices only)
              ODDP      0x40 Use Odd parity (serial devices only)
              RAW       0x20 Raw mode: wake up on all characters,
                             8-bit interface
              CRMOD     0x10 Map CR into LF; output LF as CR-LF
              ECHO      0x08 Echo (full duplex)
              CBREAK    0x02 Return each character as soon as typed
              TANDEM    0x01 Automatic flow control


              RAW and CBREAK modes were described above, in Modes.

              If the CRMOD bit is set, a line feed character  is  appended  to
              any emitted carriage return.

              The  ECHO bit controls input echoing; if enabled, any characters
              read from  the  terminal  are  echoed.   This  behavior  differs
              slightly from UNIX, where input characters are echoed as soon as
              typed.

              TANDEM mode enables automatic software  flow  control  utilizing
              the  special  characters t_startc and t_stopc in tchars (below).
              Whenever the input queue is in danger of overflowing, the system
              sends t_stopc; when the queue has drained sufficiently, t_startc
              is sent.  This mode has no effect on the console driver.

              Note: t_startc and t_stopc are used for both directions of  flow
              control;  when  t_stopc  is  received  from  a remote system (or
              user), the terminal stops output, and when t_startc is  received
              output  resumes.   Certain  drivers may also require t_stopc and
              t_startc to be the same character, in  which  case  one  or  the
              other  setting  will be ignored.  See the driver's documentation
              for details.

              The ioctl codes that apply to sgtty are:

              TIOCGETP
                     Fetch the basic parameters associated with the  terminal,
                     and store in the sgttyb structure pointed to by arg.

              TIOCSETP
                     Set the terminal's basic parameters according to the sgt-
                     tyb structure pointed to by  arg.   The  input  queue  is
                     flushed, and the call waits for the output queue to drain
                     before the parameters are changed.

              TIOCSETN
                     This is like TIOCSETP, except there is no delay  and  the
                     input queue is not flushed.

              TIOCEXCL
                     Set "exclusive-use" mode.  The terminal may not be opened
                     again by any process until all  existing  references  are
                     closed.  arg is ignored and should be the NULL pointer.

              TIOCNXCL
                     Turns  off  "exclusive-use"  mode.   arg  is  ignored and
                     should be the NULL pointer.

              TIOCHPCL
                     When the last reference to the terminal  is  closed,  the
                     terminal line is forced to hang up.  This applies only to
                     modem drivers.  arg is ignored and  should  be  the  NULL
                     pointer.

              TIOCGETD
                     The  current  line discipline number is stored in the int
                     variable pointed to by  arg.   This  value  is  currently
                     ignored.

              TIOCSETD
                     The  line  discipline  is  set  to  the  value of the int
                     pointed to by arg.

              TIOCFLUSH
                     The specified queue is flushed.  If the value pointed  to
                     by  arg  is  zero,  both  the input and output queues are
                     flushed.    If   the   value   is   FREAD   (defined   in
                     <sys/fcntl.h>), the input queue is flushed.  If the value
                     is FWRITE, the output queue is flushed.

              TIOCSTI
                     The character pointed to by arg is placed  in  the  input
                     queue as if it had been typed on the terminal.

              TIOCSBRK
                     Begins  a break sequence on the terminal.  arg is ignored
                     and should be the NULL pointer.

              TIOCCBRK
                     Ends a break sequence.  arg is ignored and should be  the
                     NULL pointer.

              TIOCSDTR
                     The  DTR line is turned on.  arg is ignored and should be
                     the NULL pointer.

              TIOCCDTR
                     The DTR line is turned off.  arg is ignored and should be
                     the NULL pointer.

              TIOCSTOP
                     Output  is  stopped  as  if t_stopc had been typed on the
                     terminal.  arg is ignored and should be the NULL pointer.

              TIOCSTART
                     If  output  is  stopped, it is resumed as if t_startc had
                     been typed on the terminal.  arg is ignored and should be
                     the NULL pointer.

              TIOCOUTQ
                     The  number of characters in the output queue is returned
                     in the int pointed to by arg.

              FIONREAD
                     The number of characters immediately available for  input
                     from  the  terminal  is returned in the int pointed to by
                     arg.  This is the preferred method  of  non-blocking  I/O
                     (checking  for the presence of characters without waiting
                     for them).

       struct tchars
              The second structure associated with a terminal defines  special
              characters.  The  structure is defined in <sys/ioctl.h> which is
              automatically included by <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 ^C, ^ ^Q, ^S, ^D and
              -1  respectively.  A value of -1 for any of the characters means
              that the effect of that character  is  ignored.   The  stop  and
              start  characters  may be the same to produce a 'toggle' effect.
              It is not recommended to set any of the other characters to  the
              same  values;  the  order  in  which  the special characters are
              checked is not defined, and the results you get may not be  what
              was expected.

              The ioctl calls that apply to tchars are:

              TIOCGETC
                     Returns  the  special  characters  settings in the tchars
                     structure pointed to by arg.

              TIOCSETC
                     The special characters are set according to tchars struc-
                     ture pointed to by arg.

       Local Mode
              The  third "structure" in the terminal interface is a local mode
              word; arg points to an int variable, which  is  broken  up  into
              bitfields.  The various bitfields in this word are as follows:

              LCRTBS    0x0001    Backspace on erase rather than echoing erase
              LPRTERA   0x0002    Printing terminal erase mode
              LCRTERA   0x0004    Erase character echoes as backspace-space-backspace
              LTILDE    0x0008    Convert ~ to ' on output (for Hazeltine terminals)
              LMDMBUF   0x0010    Stop/start output when carrier drops
              LLITOUT   0x0020    Suppress output translations
              LTOSTOP   0x0040    Send SIGTTOU for background output (not implemented)
              LFLUSHO   0x0080    Output is being flushed
              LNOHANG   0x0100    Don't send hangup when carrier drops
              LPASSOUT  0x0200    Cooked mode with 8-bit output
              LCRTKIL   0x0400    BS-space-BS erase entire line on line kill
              LPASS8    0x0800    Pass all 8 bits through on input, in any mode
              LCTLECH   0x1000    Echo input control chars as ^?
              LPENDIN   0x2000    Retype pending input at next read or input character
              LDECCTQ   0x4000    Only ^Q restarts output after ^S
              LNOFLSH   0x8000    Inhibit flushing of pending I/O when intr char is typed

              The  ioctl's used to access the local mode follow.  In all cases
              arg is a pointer to an int.

              TIOCLBIS
                     The bits of the local mode word specified by '1' bits  in
                     the argument are set; this operation is a bit-wise OR.

              TIOCLBIC
                     The  bits of the local mode word specified by '1' bits in
                     the argument are cleared; this operation ANDs  the  local
                     mode with the bitwise negation of the argument.

              TIOCLSET
                     Sets the local mode word to the value of the argument.

              TIOCLGET
                     Returns the local mode word in the int pointed to by arg.

       struct ltchars
              The fourth terminal structure is another set of special  charac-
              ters.   The  structure  is  named  ltchars  (for  Local  Special
              Characters) and is again defined in <ioctl.h>.

              struct ltchars {
                   char t_suspc;  /* stop process signal */
                   char t_dsuspc; /* delayed stop process signal */
                   char t_rprntc; /* reprint line */
                   char t_flushc; /* flush output (toggles) */
                   char t_werasc; /* word erase */
                   char t_lnextc; /* literal next character */
              };

              Defaults for these characters are ^Z, ^Y, ^R, ^O,  ^W,  and  ^V.
              As  with tchars, a value of -1 disables the effect of that char-
              acter.  Only t_suspc is currently implemented  for  the  console
              driver.

              The applicable ioctl functions are:

              TIOCSLTC
                     sets the local characters according to the ltchars struc-
                     ture pointed to by arg.

              TIOCGLTC
                     retreives the  local  characters,  storing  them  in  the
                     ltchars structure pointed to by arg.

       struct winsize
              The  fifth  structure  associated  with terminals is the winsize
              struct.  Provision is made in the kernel for storage of the cur-
              rent  window  or  terminal  size  along  with the other terminal
              information. This info is recorded in a winsize  structure,  and
              is defined in <ioctl.h>:

              struct winsize {
                   unsigned short ws_row;   /* rows, in characters */
                   unsigned short ws_col;   /* columns, in characters */
                   unsigned short ws_xpixel;     /* horizontal size, pixels */
                   unsigned short ws_ypixel;     /* vertical size, pixels */
              };

              A  '0'  in  a field indicates that the field value is undefined.
              '0' is the default when a terminal is first opened.  These  val-
              ues are not used by the terminal driver itself; rather, they are
              for the benefit of applications.  The ioctl  calls  for  winsize
              are:

              TIOCGWINSZ
                     Returns  the  window size parameters in the provided win-
                     size structure.

              TIOCSWINSZ
                     Sets the window size parameters.  If any  of  the  values
                     differ  from  the  old ones, a SIGWINCH signal is sent to
                     the terminal's process group.


FILES

       .tty
       .ttyco (console driver)
       .tty* (user-installed drivers)


SEE ALSO

       GNO Shell Reference Manual, stty(1), ioctl(2), signal(2)



GNO                              15 April 1998                          TTY(4)

Man(1) output converted with man2html