termio(7) termio(7)NAME termio - provides a general terminal interface DESCRIPTION This section describes both a particular file and the terminal interface. The file /dev/tty is, in each process, the control terminal associated with the process group of that process. Programs or shell sequences use it to ensure that their messages appear on the terminal, no matter how output is redirected. Also, programs that demand an output filename will accept /dev/tty, so the terminal being used is unimportant. The asynchronous communications ports use the same general interface, no matter what their hardware. This section discusses the common features of this interface. When a terminal file is opened, it normally makes the process wait until it establishes a connection. Users' programs seldom open these files; getty(1M) opens them and they become a user's standard input, output, and error files. The first terminal file the process-group leader opens, which is not already associated with a process group, becomes the control terminal for that process group. The control terminal plays a special role in handling quit and interrupt signals, as discussed later. The control terminal is inherited by a child process during a fork(2). A process breaks this association by changing its process group (using setpgrp(2)). Terminals associated with one of these files operate in full-duplex mode. You may type at any time, even while the terminal is printing. Characters you type are lost only when the system's character input buffers are full, which is rare, or when you have accumulated the maximum number of input characters that have not been read by some program. Currently, this limit is 256 characters. When you reach the input limit, all the saved characters are thrown away without notice. Normally, terminal input is processed in units of lines. A line is delimited by a newline (ASCII LF) character, an end-of-file (ASCII EOT) character, or an end-of-line character. This means that a program cannot read input until you have typed an entire line. Also, no matter how many characters a read(2) system call requests, a maximum of one line is returned. It is not, however, necessary to read a whole line at once; a read can request any number of characters, even one, without losing information. January 1992 1
termio(7) termio(7)Erase and kill processing is normally done during input. By default, the character DELETE erases the last character typed, but it does not erase beyond the beginning of the line. By default, the character CONTROL-U deletes the entire input line, and optionally outputs a newline character. Both these characters operate on a key-stroke basis, independent of any backspacing or tabbing that may have been done. You can escape both the erase and kill characters by preceding them with the escape character (\). The user can also change the erase and kill characters with stty(1). The following characters have special input functions. INTR (Rubout or CONTROL-C) Interrupts signal to all processes associated with the control terminal. Normally, it terminates each process, but you can arrange to have it ignore the signal or to receive a trap to an agreed-upon location; see signal(3). SWTCH (CONTROL-Z or ASCII SUB) Used by the shell layering facility, shl, to change the current layer to the control layer. QUIT (CONTROL-\ or ASCII FS) Generates a quit signal. It is identical to the interrupt signal except that, unless a receiving process has made other arrangements, it will also create a core image file (called core) in the current working directory. ERASE (DELETE) Erases the preceding character. It will not erase beyond the start of a line, as delimited by a NL, EOF, or EOL character. KILL (CONTROL-U) Deletes the entire line, as delimited by a NL, EOF, or EOL character. EOF (CONTROL-D or ASCII EOT) Generates an end-of-file from a terminal. This passes the characters waiting to be read to the program, without waiting for a newline, and discards the EOF. If no characters are waiting, (if EOF occurred at the beginning of a line) 0 characters are passed back; this is the standard end-of-file indication. NL (ASCII LF) The normal line delimiter. It cannot be changed or escaped. EOL (ASCII NUL) An additional line delimiter, like NL. It is not normally used. 2 January 1992
termio(7) termio(7)STOP (CONTROL-S or ASCII DC3) Temporarily suspends output. It is useful for preventing output from disappearing from CRT terminals before you have read it. While output is suspended, STOP characters are ignored and not read. START (CONTROL-Q or ASCII DC1) Resumes output suspended by a STOP character. While output is not suspended, START characters are ignored and not read. The start/stop characters cannot be changed or escaped. Special character functions can be disabled by changing the value in c_cc of the termio structure to '\0377'. The user can change the character values for INTR, QUIT, SWTCH, ERASE, KILL, EOF, and EOL using .BR stty (1). You can escape the ERASE, KILL, and EOF characters by preceding them with a \ character, in which case no special function is generated. When a data-set drops the carrier signal, a hangup signal is sent to all processes that have this terminal as the control terminal. Unless you have made other arrangements, this signal terminates the processes. If the hangup signal is ignored, subsequent reads return with an end-of-file indication. Thus, programs that read a terminal and test for end-of-file can terminate appropriately when hung up on. When one or more characters are written, they are 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. If 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. Several ioctl(2) system calls apply to terminal files. The primary calls use the following structure, defined in termio.h. #define NCC 8 struct termio { unsigned short c_iflag; /* input modes */ unsigned short c_oflag; /* output modes */ unsigned short c_cflag; /* control modes */ unsigned short c_lflag; /* local modes */ char c_line; /* line discipline */ unsigned char c_cc[NCC]; /* control chars */ }; January 1992 3
termio(7) termio(7)The special control characters are defined by the array c_cc. The relative positions and initial values for each function are as follows: 0 VINTR ^C 1 VQUIT FS 2 VERASE DEL 3 VKILL ^U 4 VEOF EOT 5 VEOL NUL 6 reserved 7 SWTCH NUL The c_iflag field describes the basic terminal input control. IGNBRK 0000001 Ignore break condition. BRKINT 0000002 Signal interrupt on break. IGNPAR 0000004 Ignore characters with parity errors. PARMRK 0000010 Mark parity errors. INPCK 0000020 Enable input parity check. ISTRIP 0000040 Strip character. INLCR 0000100 Map NL to CR on input. IGNCR 0000200 Ignore CR. ICRNL 0000400 Map CR to NL on input. IUCLC 0001000 Map uppercase to lowercase on input. IXON 0002000 Enable start/stop output control. IXANY 0004000 Enable any character to restart output. IXOFF 0010000 Enable start/stop input control. If IGNBRK is set, the break condition (a character framing error with all data zeros) is ignored, that is, not put in the input queue and therefore not read by any process. Otherwise if BRKINT is set, the break condition will generate an interrupt signal and flush both the input and output queues. If neither IGNBRK nor BRKINT is set, a break condition is read as a NUL (0), or if PARMRK is set, as \377, \0, \0. If IGNPAR is set, characters with other framing and parity errors are ignored. If PARMRK is set, a character with a framing or parity error that is not ignored is read as the three-character sequence: 0377, 0, X, where X is the data of the character received in error. To avoid ambiguity in this case, if ISTRIP is not set, a valid character of 0377 is read as 0377, 0377. If PARMRK is not set, a framing or parity error that is not ignored is read as the character NUL (0). If INPCK is set, input parity checking is enabled. If INPCK is not set, input parity checking is disabled. This allows output parity generation without input parity errors. 4 January 1992
termio(7) termio(7)If ISTRIP is set, valid input characters are first stripped to 7-bits; otherwise all 8-bits are processed. If INLCR is set, a received NL character is translated into a RETURN character. If IGNCR is set, a received RETURN character is ignored (not read). Otherwise if ICRNL is set, a received RETURN character is translated into a NL character. If IUCLC is set, a received uppercase alphabetic character is translated into the corresponding lowercase character. If IXON is set, start/stop output control is enabled. A received STOP character will suspend output and a received START character will restart output. All start/stop characters are ignored and not read. If IXANY is set, any input character will restart output which has been suspended. If IXOFF is set, the system will transmit START/STOP characters when the input queue is nearly empty/full. The initial input control value is all-bits-clear. The c_oflag field specifies the system treatment of output. OPOST 0000001 Postprocess output. OLCUC 0000002 Map lowercase to uppercase on output. ONLCR 0000004 Map NL to CR-NL on output. OCRNL 0000010 Map CR to NL on output. ONOCR 0000020 No CR output at column 0. ONLRET 0000040 NL performs CR function. OFILL 0000100 Use fill characters for delay. OFDEL 0000200 Fill is DEL, otherwise NUL. NLDLY 0000400 Select newline delays: NL0 0 NL1 0000400 CRDLY 0003000 Select carriage-return delays: CR0 0 CR1 0001000 CR2 0002000 CR3 0003000 TABDLY 0014000 Select horizontal-tab delays: TAB0 0 TAB1 0004000 TAB2 0010000 TAB3 0014000 Expand tabs to spaces. BSDLY 0020000 Select backspace delays: BS0 0 BS1 0020000 VTDLY 0040000 Select vertical-tab delays: VT0 0 January 1992 5
termio(7) termio(7)VT1 0040000 FFDLY 0100000 Select form feed delays: FF0 0 FF1 0100000 If OPOST is set, output characters are postprocessed as indicated by the remaining flags; otherwise characters are transmitted without change. If OLCUC is set, a lowercase alphabetic character is transmitted as the corresponding uppercase character. This function is often used in conjunction with IUCLC. If ONLCR is set, the NL character is transmitted as the CR- NL character pair. If OCRNL is set, the CR character is transmitted as the NL character. If ONOCR is set, no CR character is transmitted when at column 0 (first position). If ONLRET is set, the NL character is assumed to do the return function; the column pointer will be set to 0 and the delays specified for CR will be used. Otherwise the NL character is assumed to do just the line-feed function; the column pointer will remain unchanged. The column pointer is also set to 0 if the CR character is actually transmitted. 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. If OFILL is set, fill characters will be transmitted for delay instead of using a timed delay. This is useful for high baud terminals which need only a minimal delay. If OFDEL is set, the fill character is DEL, otherwise NUL. If a form feed or vertical tab delay is specified, it lasts for about 2 seconds. Newline delay lasts about 0.10 seconds. If ONLRET is set, the return delays are used instead of the newline delays. If OFILL is set, two fill characters will be transmitted. Return delay type 1 is dependent on the current column position, type 2 is about 0.10 seconds, and type 3 is about 0.15 seconds. If OFILL is set, delay type 1 transmits two fill characters, and type 2, four fill characters. Horizontal tab delay type 1 is dependent on the current column position. Type 2 is about 0.10 seconds. Type 3 specifies that tabs are to be expanded into spaces. If OFILL is set, two fill characters will be transmitted for any delay. 6 January 1992
termio(7) termio(7)Backspace delay lasts about 0.05 seconds. If OFILL is set, one fill character will be transmitted. The actual delays depend on line speed and system load. The initial output control value is all bits clear. The c_cflag field describes the hardware control of the terminal: CBAUD 0000017 Baud rate: B0 0 Hang up B50 0000001 50 baud B75 0000002 75 baud B110 0000003 110 baud B134 0000004 134.5 baud B150 0000005 150 baud B200 0000006 200 baud B300 0000007 300 baud B600 0000010 600 baud B1200 0000011 1200 baud B1800 0000012 1800 baud B2400 0000013 2400 baud B4800 0000014 4800 baud B9600 0000015 9600 baud B19200 0000016 19200 baud B38400 0000017 38400 baud EXTA 0000016 External A EXTB 0000017 External B CSIZE 0000060 Character size: CS5 0 5 bits CS6 0000020 6 bits CS7 0000040 7 bits CS8 0000060 8 bits CSTOPB 0000100 Send two stop bits, otherwise one. CREAD 0000200 Enable receiver. PARENB 0000400 Parity enable. PARODD 0001000 Odd parity, otherwise even. HUPCL 0002000 Hang up on last close. CLOCAL 0004000 Local line, otherwise dial-up. LOBLK 0010000 Block layer output. The CBAUD bits specify the baud rate. The zero baud, B0, is used to hang up the connection. If B0 is specified, the data-terminal-ready signal will not be asserted. Normally, this will disconnect the line. For any particular hardware, impossible speed changes are ignored. The CSIZE bits specify the character size in bits for both transmission and reception. This size does not include the parity bit, if any. If CSTOPB is set, two stop bits are used, otherwise one stop bit. For example, at 110 baud, two January 1992 7
termio(7) termio(7)stops bits are required. If PARENB is set, parity generation and detection is enabled and a parity bit is added to each character. If parity is enabled, the PARODD flag specifies odd parity if set, otherwise even parity is used. If CREAD is set, the receiver is enabled; otherwise no characters will be received. If HUPCL is set, the line will be disconnected when the last process with an open line closes it or terminates. That is, the data-terminal-ready signal will not be asserted. If CLOCAL is set, the line is assumed to be a local, direct connection with no modem control; otherwise modem control is assumed. If LOBLK is set, the output of a job control layer will be blocked when it is not the current layer; otherwise the output generated by that layer will be multiplexed onto the current layer. The initial hardware control value after open is B300, CS8, CREAD, HUPCL. The c_lflag field of the argument structure is used by the line discipline to control terminal functions. The basic line discipline (0) provides the following: ISIG 0000001 Enable signals. ICANON 0000002 Canonical input (erase and kill processing). XCASE 0000004 Canonical upper/lower presentation. ECHO 0000010 Enable echo. ECHOE 0000020 Echo erase character as BS-SP-BS. ECHOK 0000040 Echo NL after kill character. ECHONL 0000100 Echo NL. NOFLSH 0000200 Disable flush after interrupt or quit. If ISIG is set, each input character is checked against the special control characters INTR, SWTCH, and QUIT. If an input character matches one of these control characters, the function associated with that character is performed. If ISIG is not set, no checking is done. Thus these special input functions are possible only if ISIG is set. These functions may be disabled individually by changing the value of the control character to an unlikely or impossible value (for example, 0377). If ICANON is set, canonical processing is enabled. This enables the erase and kill edit functions, and the assembly of input characters into lines delimited by NL, EOF, and 8 January 1992
termio(7) termio(7)EOL. If ICANON is not set, read requests are satisfied directly from the input queue. A read will not be satisfied until at least MIN characters have been received or the timeout value TIME has expired between characters. This allows fast bursts of input to be read efficiently while still allowing single character input. The MIN and TIME values are stored in the position for the EOF and EOL characters, respectively. The time value represents tenths of seconds. If XCASE is set, and if ICANON is set, an uppercase letter is accepted on input by preceding it with a \ character, and on output is preceded by a \ character. In this mode, the following escape sequences are generated on output and accepted on input: for: use: ` \' | \! ~ \^ { \( } \) \ \\ For example, A is input as \a, \n as \\n, and \N as \\\n. If ECHO is set, characters are echoed as received. When ICANON is set, the following echo functions are possible. If ECHO and ECHOE are set, the erase character is echoed as ASCII BS SP BS, which will clear the last character from a CRT screen. If ECHOE is set and ECHO is not set, the erase character is echoed as ASCII SP BS. If ECHOK is set, the NL character will be echoed after the kill character to emphasize that the line will be deleted. Note that an escape character preceding the erase or kill character removes any special function. If ECHONL is set, the NL character will be echoed even if ECHO is not set. This is useful for terminals set to local echo (so-called half duplex). Unless escaped, the EOF character is not echoed. Because EOT is the default EOF character, this prevents terminals that respond to EOT from hanging up. If NOFLSH is set, the normal flush of the input and output queues associated with the quit, switch, and interrupt characters will not be done. The initial line-discipline control value is all bits clear. The primary ioctl(2) system calls have the form January 1992 9
termio(7) termio(7)ioctl (fildes, command, arg) struct termio *arg; The commands using this form are TCGETA Get the parameters associated with the terminal and store in the termio structure referenced by arg. TIOCGPGRP The current terminal process group is placed into the word at the address contained in arg. TIOCSPGRP The address pointed to by arg contains a word, typically a process ID, that becomes the process group for the controlling terminal. TCSETA Set the parameters associated with the terminal from the structure referenced by arg. The change is immediate. TCSETAW Wait for the output to drain before setting the new parameters. This form should be used when changing parameters that will affect output. TCSETAF Wait for the output to drain, flush the input queue, and set the new parameters. Additional ioctl(2) calls have the form: ioctl (fildes, command, arg) int arg; The commands using this form are TCSBRK Wait for the output to drain. If arg is 0, then send a break (zero bits for 0.25 seconds). TCXONC Start/stop control. If arg is 0, suspend output; if 1, restart suspended output; if 2, suspend input; if 3, restart suspended input. TCFLSH If arg is 0, flush the input queue; if 1, flush the output queue; if 2, flush both the input and output queues. 10 January 1992
termio(7) termio(7)The following ioctl(2) calls take the form ioctl(fildes, command, 0) They are for modem control; not all devices support all or any of them. If any are supported then UIOCTTSTAT is supported. The default is UIOCNOMODEM/UIOCNOFLOW. All these are ``remembered'' when a device is closed and reopened again. The following are mutually exclusive (on some systems DTR/DCD are named in reverse order: here DCD is the input, DTR the output). UIOCMODEM Modem control (DTR/DCD) is enabled (DCD is required before a device can be opened, if it is removed the device is ``hung up,'' and on opening DTR is asserted); the default is ``on'' for /dev/modem and /dev/tty0. UIOCEMODEM ``European style'' modem control. Like UIOMODEM except that DTR is not asserted until RI (ring interrupt) is detected. UIOCNOMODEM No modem control. DTR is still asserted, DCD is ignored, and opens always complete without waiting. UIOCDTRFLOW The DCD (on some printers this is the DTR line) is used for flow control. It must be asserted before characters can be transmitted; the default is ``on'' for /dev/printer and /dev/tty1. The next two commands are also mutually exclusive. Again, CTS/RTS are sometimes named in reverse order. Here RTS is the output, CTS the input. UIOCNOFLOW Hardware flow control is disabled. RTS is asserted before transmitting (or asserted all the time). CTS is ignored. UIOCFLOW Hardware flow control is enabled. RTS is asserted before transmitting. CTS must be asserted by the other end before transmission can start. (This is required for every character.) UIOCTTSTAT This returns 3 bytes. The first is 1 if UIOCMODEM is January 1992 11
termio(7) termio(7)enabled. The second is 1 if UIOCDTRFLOW is enabled and the third is 1 if UIOCFLOW is enabled. The following ioctl(2) calls have the form ioctl(fildes, command, pArg) int *pArg; The commands that use this form are FIONREAD Return the number of characters currently in a terminal's input buffer into the integer pointer *pArg. FIONBIO If the integer referenced by the pointer pArg is 1, then turn on nonblocking IO. If it is 0, turn it off. If nonblocking IO is turned on, then read or write will return without blocking (and return the error EWOULDBLOCK) if it is not possible to complete the transfer immediately. FIOASYNC If the integer referenced by the pointer pArg is 1, turn on I/O signalling. If it is 0, turn it off. If I/O signalling is turned on then the signal SIGIO will be sent whenever input is available to the device. Care should be taken that all the processes in the tty's process group can respond to (or ignore) this signal if it is enabled. Some devices are streams based. In order for them to respond to the ioctl calls discussed here, the streams module (line discipline) line must be pushed on the stream. For most logged in terminals, this is done by /etc/getty as part of the logging in process. Refer to streams(7) and line_push(3) for more information about how to do this if it is required. SERIAL MANAGER SUPPORT The following new ioctl calls were added to support the Serial Manager running under A/UX 2.0. Five of the calls have the form: ioctl(fildes, command, 0) The commands using this form are as follows: TCRESET Reset the serial line identified by filedes. TCSETDTR 12 January 1992
termio(7) termio(7)Drive the DTR line high for the serial line identified by filedes. This turns DTR on. TCCLRDTR Drive the DTR line low for the serial line identified by filedes. This turns DTR off. TCSBRKM Set break mode for the serial line identified by filedes. This starts a line break signal. TCCBRKM Clear break mode for the serial line identified by filedes. This terminates a line break signal. Two of the calls have the form: ioctl (fildes, command, arg) int *arg; The commands using this form are as follows: TCSETSTP Set the stop character for flow control for the serial line identified by filedes. arg points to a byte containing the new stop character. TCSETSTA Set the start character for flow control for the serial line identified by filedes. arg points to a byte containing the new start character. One call has the form: ioctl (fildes, command, arg) struct serstat *arg; where the serstat structure has the following format: January 1992 13
termio(7) termio(7)struct serstat { unsigned long ser_frame; /*framing errors*/ unsigned long ser_ovrun; /*overrun errors*/ unsigned long ser_parity; /*parity errors */ unsigned long ser_cts; /*CTS signal */ unsigned long ser_inflow; /*input flow */ /*control */ unsigned long ser_outflow; /*output flow */ /*control */ }; The command using this form is as follows: TCGETSTAT Get status information for the serial identified by filedes and store it in the B termio structure referenced by arg. The ser_frame, ser_ovrun, and ser_parity members of the serstat structure represent the error counts that have been tallied since the last call to TCGETSTAT. The ser_cts member indicates the current status of the CTS signal. A true value indicates that CTS is on (high); otherwise, CTS is off (low). If the ser_inflow member is true, input is currently blocked due to flow control. If the ser_outflow member is true, output is currently blocked due to flow control. 4.2 BSD COMPATIBLE FEATURES Local special characters When job control is active, there is a ltchars structure associated with each terminal. Two fields are used, which define characters to stop a process. The other fields are for compatibility with past and future systems. struct ltchars { char t_suspc; /* stop process signal */ char t_dsuspc; /* delayed stop process */ /* signal */ char t_rprntc; /* Not used */ char t_flushc; /* Not used */ char t_werase; /* Not used */ char t_lnextc; /* Not used */ }; By default, these characters are disabled (set to -1). Traditionally CONTROL-Z is used for the suspend character and CONTROL-Y for the delayed suspend. TIOCSLTC The arg parameter to the ioctl call (as shown above) is the address of a ltchars structure which defines the new local characters. 14 January 1992
termio(7) termio(7)TIOCGLTC The arg parameter to the ioctl is the address of a ltchars structure into which the current set of special characters is placed. Compatibility modes An additional mode word is recognized by the BSD compatible TTY driver. It is used to set and clear the job control ``tostop'' bit. When set, processes running in the background which write on the terminal will be sent a SIGTTOU signal. When BSD compatible signals are used, background processes which read from TTY will be sent SIGTTIN. TOSTOP 0x1-Send SIGTTOU for background output. TIOCSCOMPAT The arg parameter to the ioctl call is the address of an integer containing the new value of the compatibility mode word. TIOCGCOMPAT The arg parameter is the address of an integer variable chosen to receive the new compatibility mode word. FILES /dev/tty Device file /dev/tty* Device file /dev/console Device file SEE ALSO fork(2), ioctl(2), read(2), setpgrp(2), line_push(3), signal(3) streams(7) stty(1) in A/UX Command Reference getty(1M), in A/UX System Administrator's Reference January 1992 15