Content-type: text/html
tty - General terminal interface
#include <sys/termios.h>
This section describes both a particular special file /dev/tty and the terminal drivers used for conversational computing. Much of the terminal interface performance is governed by the settings of a terminal's termios structure. This structure provides definitions for terminal input and output processing, control and local modes, and so on. These definitions are found in the termios.h header file.
The STREAMS-based line discipline is implemented as the STREAMS module ldterm. This line discipline performs most of the functions defined by the termios interface for session management and character processing but not some low level device control. In order to determine if a terminal device is implemented as a STREAMS device, use the libc function isastream on the open file descriptor. See the isastream(3) reference page.
Users can switch line disciplines by using the command strchg or the I_POP or I_PUSH STREAMS ioctls. The ldterm line discipline is the only STREAMS-based line discipline provided by the base operating system for use with terminals. However, additional STREAMS modules to support features needed in countries other than the United States can be pushed above and below the ldterm module.
The operating system supports several clist-based line disciplines for controlling communication lines. By default, the Standard line discipline, which supports full POSIX terminal semantics, is the only line discipline available for terminals. However, after the installation of worldwide portability subsets, two additional line disciplines are available for processing the multibyte and single-byte coded character sets used for Asian languages. The atty(7) and ttty(7) reference pages, which are also available after the worldwide portability subsets are installed, describe these additional line disciplines.
Line discipline switching is done with the TIOCSETD ioctl for clist-based terminal drivers. The following example illustrates how to switch line disciplines:
int ldisc = LDISC;
ioctl(fd,TIOCSETD,&ldisc);
In this example, LDISC is the index into the linesw table. (See the /sys/bsd/tty_conf.c file.)
Other clist disciplines exist for special purposes, such as communication lines for network devices. The current line discipline can be obtained with the TIOCGETD ioctl for clist-based terminal drivers. Pending output is discarded when the line discipline is changed. When the Standard line discipline is used, NTTYDISC (value 2) is returned by default for BSD compatibility. TTYDISC (value 0) is returned only when you compile the application with the -D_USE_NEW_TTY switch. When the atty or ttty line discipline is used, ASYDISC (value 9) or TSBDISC (value 10) is returned, respectively.
In earlier versions of UNIX systems, a controlling terminal was implicitly assigned
to a process if, at the time an open was done on the terminal, the terminal
was not the controlling terminal for any process, and if the process doing
the open did not have a controlling terminal.
In this version of UNIX, in accordance
with POSIX 1003.1, a process must be a session leader to allocate
a controlling terminal.
In addition, the allocation is now done explicitly with a call to ioctl().
(This implies that the O_NOCTTY flag to the open() function
is ignored.)
The following example illustrates the correct sequence for obtaining
a controlling tty (no error checking is shown).
This code fragment calls the setsid() function to make the
current process the
group and session leader, and to remove any controlling tty that
the process may already have. It then opens the console device and
attaches it to the current session as the controlling terminal.
Note that the process must not already be a session or process group
leader, and the console must not already be the controlling tty of
any other session.
(void)setsid(); /* become session leader and */
/* lose controlling tty */
fd = open("/dev/console", O_RDWR);
(void)ioctl(fd,TIOCSCTTY,0);
A process can remove the association it has with its controlling terminal by opening the /dev/tty file and issuing the following call: ioctl(fd, TIOCNOTTY, 0);
For example:
fd = open("/dev/tty", O_RDWR);
if (fd > = 0) {
ioctl(fd,TIOCNOTTY,0);
close(fd);
}
If the calling process is not the session leader, the process group of the calling process is set to 0.
When a control terminal file is closed, pending input is removed, and pending output is sent to the receiving device.
When a terminal file is opened, the process blocks until a carrier signal is detected. If the open() function is called with the O_NONBLOCK flag set, however, the process does not wait. Instead, the first read() or write() call will wait for carrier to be established. If the CLOCAL mode is set in the termios structure, the driver assumes that modem control is not in effect, and open(), read(), and write() therefore proceed without waiting for a carrier signal to be established.
Each process group belongs to a session. Each process in the process group also belongs to the process group's session. A process which is not the process group leader can create its own session and process group with a call to the setsid() function. That calling process then becomes the session leader of the new session and of the new process group. The new session has no controlling terminal until the session leader assigns one to it. The calling process's ID is assigned to the new process group. With the setpgid() function, other processes can be added to a process group.
A controlling terminal can have a distinguished process group associated with it known as the foreground process group. The terminal's foreground process group is the one that receives signals generated by the INTR, QUIT, and SUSP special control characters. Certain operations on the terminal are also restricted to processes in the terminal's foreground process group (see "Terminal Access Control"). A terminal's foreground process group may be changed by calling the tcsetpgrp() function. A terminal's current foreground process group may be obtained by calling the tcgetpgrp() function.
Erase and kill processing is performed on input that has not been terminated by one of the line termination characters. Erase processing removes the last character in the line, kill processing removes the whole line. This mode eliminates erase and kill processing, making input characters available to the user program as they are typed. Input is not processed into lines. The received bytes are processed according to the values at the VMIN and VTIME indexes of the c_cc array in the termios structure. MIN is the minimum number of bytes the terminal can receive in noncanonical mode before a read is considered successful. TIME, measured in 0.1 second granularity, times out sporadic input.
These cases are summarized as follows: In this case, TIME is an interbyte timer that is activated after the first byte of the input line is received, and reset after each byte is received. The read operation is a success if MIN bytes are read before TIME runs out. If TIME runs out before MIN bytes have been received, the characters that were received are returned. In this case, only MIN is used. A queued read() waits until MIN bytes are received, or a signal is received. In this case, TIME is used as a read timer that starts when a read() call is made. The read() call is finished when one byte is read, or when TIME runs out. In this case, either the number of requested bytes or the number of currently available bytes is returned, depending on which is the lesser number. The read() function returns a zero if no data was read.
Canonical mode is entered by setting the ICANON flag of the c_lflag field in the in the terminal's termios structure. Other input processing is performed according to the other flags set in the c_iflag and c_lflag fields.
Input characters are normally accepted in either even or odd parity with the parity bit being stripped off before the character is given to the program. The ISTRIP mask of the c_iflag field controls whether the parity bit is stripped (ISTRIP set) or not stripped (ISTRIP not set). By setting the PARENB flag in the c_cflag field, and either setting (not setting) the PARODD flag, it is possible to have input characters with EVEN (ODD) parity discarded or marked (see "Input Modes").
In all of the line disciplines, it is possible to simulate terminal input using the TIOCSTI ioctl, which takes, as its third argument, the address of a character. The system pretends that this character was typed on the argument terminal, which must be the control terminal for the process, unless the process has superuser privileges.
Input characters are normally echoed by putting them in an output queue as they arrive. This may be disabled by clearing the ECHO bit in the c_lflag word using the tcsetattr() call or the TIOCSETA, TIOCSETAW, or TIOCSETAF ioctls.
In canonical mode, terminal input is processed in units of lines. A program attempting to read will normally be suspended until an entire line has been received (but see the description of SIGTTIN in "Terminal Access Control"). 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. In read() requests, the O_NONBLOCK flag affects the read() operation behavior.
If O_NONBLOCK is not set, a read() request is blocked until data or a signal has been received. If the O_NONBLOCK flag is set, the read() request is not blocked, and one of the following situations holds: Some data may have been typed, but there may or may not be enough data to satisfy the entire read request. In either case, the read() function returns the data available, returning the number of bytes of data it read. If there is no data for the read operation, the read() returns a -1 with an error of EAGAIN.
During input, line editing is normally done with the erase special control character (VERASE) logically erasing the last character typed and the kill special control character (VKILL) logically erasing the entire current input line. These characters never erase beyond the beginning of the current input line or an EOF (End-of-File). These characters, along with the other special control characters, may be entered literally by preceding them with the literal-next character (VLNEXT --- default ^V).
The drivers normally treat either a newline character (`\n'), End-of-File character (EOF), or End-of-Line character (EOL) as terminating an input line, echoing a return and a line feed. If the ICRNL character bit is set in the c_iflag word then carriage returns are translated to newline characters on input, and are normally echoed as carriage return-linefeed sequences. If ICRNL is not set, this processing for carriage return is disabled, and it is simply echoed as a return, and does not terminate cooked mode input.
The POSIX terminal driver also provides two other editing characters in normal mode. The word-erase character, normally <Ctrl-W>, is a c_cc structure special control character VWERASE. This character erases the preceding word, but not any spaces before it. For the purposes of <Ctrl-W>, a word is defined as a sequence of nonblank characters, with tabs counted as blanks. However, if the ALTWERASE flag is set in the c_lflag word, then a word is considered to be any sequence of alphanumerics or underscores bounded by characters that are not alphanumerics or underscores. Finally, the reprint character, normally <Ctrl-R>, is a c_cc structure special control character VREPRINT. This character retypes the pending input beginning on a new line. Retyping occurs automatically in canonical mode if characters which would normally be erased from the screen are fouled by program output.
The input mode mask bits can be combined for the following results:
The setting of IGNBRK causes input break conditions to be ignored. If IGNBRK is not set, but BRKINT is set, the break condition has the same effect as if the VINTR control character had been typed. If neither IGNBRK nor BRKINT are set, then the break condition is input as a single character '\0'. If the PARMRK flag is set, then the input is read as three characters, '\377', '\0', and '\0'.
The setting of IGNPAR causes a byte with a parity or framing error, except for breaks, to be ignored (that is, discarded). If IGNPAR is not set, but PARMRK is set, a byte with parity or framing error, except for breaks, is passed as the three characters '\377', '\0', and X, where X is the character data received in error. If the ISTRIP flag is not set, the valid character '\377' is passed as '\377', '377'. If both PARMRK and IGNPAR are not set, framing or parity errors, including breaks, are passed as the single character '\0'.
The setting of INPCK enables input parity checking. If input parity checking is not enabled (INPCK not set), then characters with parity errors are simply passed through as is. The enabling/disabling of input parity checking is independent of the generation of parity on output.
Setting ISTRIP causes the eighth bit of the eight valid input bits to be stripped before processing. If this mask is not set, all eight bits are processed.
Setting INLCR causes a newline character to be read as a carriage return character. If the IGNCR flag is also set, the carriage return is ignored. If the IGNCR flag is not set, INLCR works as described earlier.
The STOP character (normally <Ctrl-S>) suspends output and the START character (normally <Ctrl-Q>) restarts output. Setting IXON enables stop/start output control, in which the START and STOP characters are not read, but rather perform flow control functions. Extra stop characters typed when output is already stopped have no effect, unless the start and stop characters are made the same, in which case output resumes. Disabling IXON causes the START and STOP characters to be read.
Setting IXOFF enables stop/start input control. When this flag is set, the terminal device will be sent STOP characters to halt the transmission of data when the input queue is in danger of overflowing (exceed MAX_INPUT). When enough characters have been read to reduce the amount of data queued to an acceptable level, a START character is sent to the device to allow it to continue transmitting data. This mode is useful when the terminal is actually another machine that obeys those conventions.
The terminal drivers provide necessary processing for canonical and noncanonical mode output including delay generation for certain special characters and parity generation. Delays are available after backspaces (BSDLY), formfeeds (FFDLY), carriage returns (CRDLY), tabs (TABDLY) and newlines (NLDLY). The driver will also optionally expand tabs into spaces, where the tab stops are assumed to be set every eight columns, and optionally convert newlines to carriage returns followed by newline. Output process is controlled by bits in the c_oflag field of the termios structure. Refer to the write(2) reference page for a description of the O_NONBLOCK flag.
The terminal drivers provide for mapping from lowercase to uppercase (OLCUC) for terminals lacking lower case, and for other special processing on deficient terminals.
Finally, the terminal driver, supports an output flush character, normally <Ctrl-O>, which sets the FLUSHO bit in the local mode word, causing subsequent output to be flushed until it is cleared by a program or more input is typed. This character has effect in both canonical and noncanonical modes and causes any pending input to be retyped. An ioctl to flush the characters in the input or output queues, TIOCFLUSH, is also available.
When the carrier signal from the dataset drops (usually because the user has hung up his terminal) a SIGHUP hangup signal is sent to the processes in the distinguished process group of the terminal; this usually causes them to terminate. The sending of SIGHUP does not take place if the CLOCAL bit is set in c_cflag field of the driver. Access to the terminal by other processes is then normally revoked, so any further reads will fail, and programs that read a terminal and test for End-of-File on their input will terminate appropriately.
If a process attempts to write to its controlling terminal when the process is not in the foreground process group of the terminal, and the TOSTOP bit is set in the c_lflag word of the termios structure, that background process group is sent a SIGTTOU signal and the process is prohibited from writing. If TOSTOP is not set, or if TOSTOP is set and the process is blocking or ignoring the SIGTTOU signal, process writes to the terminal are allowed, and the SIGTTOU signal is not sent. If TOSTOP is set, if the writing process' process group is orphaned, and if SIGTTOU is not blocked by the writing process, the write operation returns a -1 with errno set to [EIO], and does not a send a signal.
#include <sys/termios.h>
ioctl(fildes, code, arg) struct termios *arg;
The applicable codes are: Gets the termios structure and all its associated parameters. The interface delays until output is quiescent, then throws away any unread characters. Sets the parameters according to the termios structure. Drains the output before setting the parameters according to the termios structure. Sets the parameters like TIOCSETA. Drains the output and flushes the input before setting the parameters according to the termios structure. Sets the parameters like TIOCSETA.
With the following codes arg is ignored: Set ``exclusive-use'' mode: no further opens are permitted until the file has been closed. Turn off ``exclusive-use'' mode.
With the following codes arg is a pointer to an int: If the int pointed to by arg has a zero value, all characters waiting in input or output queues are flushed. Otherwise, the value of the int is for the FREAD and FWRITE bits defined in the sys/file.h file; if the FREAD bit is set, all characters waiting in input queues are flushed, and if the FWRITE bit is set, all characters waiting in output queues are flushed.
With the following codes, arg is a pointer to an int: The arg parameter is a pointer to the value representing the process group ID of the process group, and is returned by the controlling terminal specified by the filedes parameter. See tcgetpgrp(3) for more information on error codes that can occur if this ioctl fails. The arg parameter is a pointer to the value to which the process group ID for the terminal specified by the filedes parameter will be set. This terminal must be the controlling terminal and must be associated with the calling process's session. The process group value must match a process group ID of a process in the same session as the calling process. See tcsetpgrp for more information on error codes that can occur if this ioctl fails.
Sets all modem bits. The arg parameter is a pointer to an int, which specifies the modem bits to be set. arg is a pointer to an int, which specifies the modem bits to be cleared. Gets all the modem bits and returns them in the int point to by arg.
A value of 0 (zero) in any field is interpreted as ``undefined;'' the entire structure is zeroed on final close.
The applicable ioctl functions are: The arg parameter is a pointer to a struct winsize into which will be placed the current terminal or window size information. The arg parameter is a pointer to a struct winsize, which will be used to set the current terminal or window size information. If the new information is different than the old information, a SIGWINCH signal will be sent to the terminal's process group.
The following System V and BSD ioctls are currently supported as a compatibility interface for System V and older BSD system programs. They should not be used in new applications. The ioctl call has the following format:
ioctl (fdes, cmd, arg)
The System V termio ioctls use a pointer to a termio structure for the arg parameter. The following include is required for the System V termio ioctls:
#include <sys/termio>
The parameters of the tty driver are set/returned by translating the termio structure to/from a termios structure. Gets termio structure. Sets termio structure. Drains output and then sets termio structure. Drains output, flushes input, and then sets termio structure.
The following group of System V ioctls take an integer value for the arg parameter. Sends break. Sends break. Sets flow control. The arg parameter uses same values as the POSIX function tcflow() (must include <sys/termios.h>) Flushes queue(s). You must include <sys/fcntl.h> for valid arg parameters (for example, FREAD for flushing input side).
The following group of BSD compatibility ioctls use a pointer to a sgttyb structure for the arg parameter. The tty parameters of the tty driver are set/returned by translating the sgttyb structure to/from a termios structure. Returns tty parameters. Sets tty parameters. Sets tty parameter without flushing.
The next group uses a pointer to the local mode bits (an integer value) as their arg parameter. The local mode bits are converted to the appropriate POSIX termios flag settings. The arg value is used as a mask to set the local mode bits. The arg value is used as a mask to clear the local mode bits. The arg value is used to replace the current setting of the local mode bits. The arg parameter is used to return the current value of the local mode bits.
The following group uses a pointer to a ltchars structure as their arg parameter. The local special characters are translated to POSIX termios control characters. Set local control characters. Get local control characters.
The following group of BSD compatibility ioctls sets/clears the POSIX CLOCAL and HUPCL flags. The CLOCAL flag turns modem control on/off in the tty driver. If the arg parameter (a pointer to an integer) for TIOCMODEM/TIOCNMODEM is nonzero and the requesting process has super user privileges the change is made permanent. Otherwise after the last close, the tty line reverts back to the default value. The HUPCL flag determines if the terminal line should be disconnected (that is, DTR is non asserted) after the last close. The TIOCHPCL ioctl ignores the arg parameter. Sets CLOCAL. Clears CLOCAL. Sets HUPCL.
Functions: ioctl(2), sigvec(2), tcsetattr(3), tcgetattr(3), tcdrain(3), tcflush(3), tcsendbreak(3), tcgetpgrp(3), tcsetpgrp(3).
Commands: csh(1), strchg(1), tset(1), getty(8).
Files: termios(4)
Interfaces: atty(7), ldterm(7), modem(7), ttty(7).
IEEE Std POSIX 1003.1-1988 delim off