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 interface, 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 process' controlling terminal is inherited from its parent. By opening the special file .tty, a process can access its controlling terminal. This is useful where the input and output of a process was redirected and the process wants to be sure of getting 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 signal-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 interface 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 available, 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 processing 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 settings 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 sgttyb 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 structure 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 characters. 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 character. Only t_suspc is currently implemented for the console driver.

    The applicable ioctl functions are:

    TIOCSLTC
        sets the local characters according to the ltchars structure 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 current 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 values 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 winsize 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)