termios(7P) termios(7P)NAME termios - A/UX(Reg.) POSIX general terminal interface SYNOPSIS #include <termios.h> DESCRIPTION Part of the A/UX POSIX environment is a general terminal in- terface for controlling asynchronous communications ports. When a terminal file is opened, it normally causes the pro- cess to wait until the connection is established. In prac- tice, user programs seldom open these files; getty(1M) opens them, and they become a user's standard input, output, and error files. 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 ap- pear on the terminal, no matter how output is redirected. Also, programs that demand an output filename accept /dev/tty, so it is not necessary to determine which terminal is being used. Opening a terminal device causes the process to block until the connection is established. If the O_NONBLOCK flag is set, open(2) returns a file descriptor without waiting for the connection to be established. A terminal may have a foreground process group associated with it. Certain characters have special functions on input or output. The foreground process group plays a role in the handling of signal-generating characters. Shells that support job control can allocate the terminal to different jobs, or process groups, by placing related processes in a single process group and associating this process group with the terminal. The associated process group of a terminal may be set or examined by a process in the process group by using tcsetpgrp(3P) and tcgetpgrp(3P). A terminal may belong to a process as its controlling termi- nal. Each process of a session that has a controlling termi- nal has the same controlling terminal. A terminal may be the controlling terminal for at most one session. If the process ID of the calling process is equal to the process group ID and the process has no controlling terminal, the next open of a terminal without a controlling process causes the opened terminal to become the controlling terminal for the process. If a process that is not a session leader opens a terminal file or the O_NOCTTY flag is used when cal- ling open, the terminal does not become the controlling ter- April, 1990 1
termios(7P) termios(7P)minal of the process. If the O_GETCTTY flag is used when calling open, the terminal becomes the controlling terminal of the calling process. When a controlling terminal becomes associated with a session, its foreground process group is set to the process group of the session leader. The controlling terminal is inherited by a child process during a fork (see fork(2)). A process relinquishes its controlling terminal when it changes its process group by using setsid(2). When a controlling process terminates, the foreground process group of its controlling terminal is set to 0. This allows the terminal to be acquired as a control- ling terminal by a new process group of the session leader. A terminal device associated with a terminal device file may operate in full-duplex mode so that characters may arrive even while output is occurring. Each terminal device file has associated with it an input queue, into which incoming characters are placed by the system before being read by a process. The system imposes a limit, MAX_INPUT, on the number of bytes that may be stored in the input queue. If MAX_INPUT is exceeded, the queue is flushed. A terminal device file may be in canonical mode or noncanon- ical mode. The mode of the terminal device file determines the method of input processing. In canonical-mode input processing, terminal input is pro- cessed in units of lines. A line is delimited by a newline (\n) character and an end-of-file (EOF) or end-of-line (EOL) character. This means that a read request is not satisfied until an entire line is typed or a signal is received. Also, no matter how many characters are requested by the read, at most one line is returned. It is not necessary to read a whole line at once; any number of characters, even one, may be requested in a read without losing information. MAX_CANON is the limit on the number of bytes in a line. If this limit is exceeded, the input buffer is flushed. Erase and kill processing occurs during canonical-mode input pro- cessing. In noncanonical-mode input processing, input characters are not assembled into lines, and erase and kill processing does not occur. The values of the special characters MIN and TIME are used to determine how to process the characters re- ceived. MIN and TIME are defined in the c_cc array of spe- cial control characters. MIN represents the minimum number of characters that should be received when the read is satisfied. TIME is a timer of 0.1 second granularity that is used to time out data charac- terized by short bursts and short-term data transmissions. 2 April, 1990
termios(7P) termios(7P)The four possible combinations for MIN and TIME are as fol- lows: MIN>0, TIME>0 In this case TIME serves as an interbyte timer and is activated after the first byte is received. Since it is an interbyte timer, it is reset after a byte is re- ceived. When the first byte is received, the interbyte timer is started. If MIN bytes are received before the timer expires, the read is satisfied. If the timer ex- pires before MIN bytes are received, the bytes received to that point are returned to the user. Note that if TIME expires, at least one byte is returned because the timer is not started unless a byte has been received. In this case, the read blocks until the MIN and TIME mechanisms are activated by the receipt of a byte. MIN>0, TIME=0 When the value of TIME is 0, the timer plays no role, and only MIN is significant. A pending read is not sa- tisfied until MIN bytes are received. A program that sets TIME to 0 when reading record-based terminal I/O may block indefinitely on a read operation. MIN=0, TIME>0 When MIN is 0, TIME no longer represents an interbyte timer. TIME now serves as a read timer that is activat- ed as soon as the read(2) is processed. A read is sa- tisfied as soon as a single byte is received or the read timer expires. Note that if the timer expires, no byte is returned. If the timer does not expire, the only way the read can be satisfied is if a byte is received. In this case, reads do not block indefinitely waiting for a byte; if no byte is received within TIME*0.1 seconds after the read is initiated, the read returns 0 bytes. MIN=0, TIME=0 The minimum of either the number of bytes requested or the number of bytes currently available is returned without waiting for more bytes to be received. Reads are also dependent on the whether the O_NONBLOCK flag is set by the open(2) or fcntl(2) call. If the O_NONBLOCK flag is not set, then a read request blocks until data is available or a signal is received. If the O_NONBLOCK flag is set, then a read completes without blocking in one of three ways: 1.If there is enough data available to satisfy the entire request, the read completes successfully, having read all the requested data, and returns the number of bytes read. April, 1990 3
termios(7P) termios(7P)2.If there is not enough data available to satisfy the en- tire request, the read completes successfully, having read as much data as possible, and returns the number of bytes it was able to read. 3.If there is no data available, the read returns -1, and errno is set to EAGAIN. Any attempt by a process in a background process group to read from its controlling terminal causes its process group to be sent a SIGTTIN signal unless the reading process is ignoring or blocking SIGTTIN , or the process group of the reading process is orphaned. Then the read(2) returns -1 with errno set to EI0, and no signal is sent. The default action of SIGTTIN is to stop the process to which it is sent. Any attempt by a process in a background process group to write to its controlling terminal will cause the process group to be sent a SIGTTOU signal unless one of the follow- ing special cases apply: If TOSTOP is not set, or if TOSTOP is set and the process is ignoring or blocking SIGTTOU, the process is allowed to write to the terminal, and SIGTTOU is not sent. If TOSTOP is set and the process group of the writing process is orphaned and if the writing process is not ignoring or blocking SIGTTOU, the write(2) returns -1 with errno set to EI0, and no signal is sent. Routines that need to control terminal characteristics do so by modifying the termios structure for the device. This structure is defined in <termios.h> as follows: struct termios { lcflag_t long c_iflag; lcflag_t long c_oflag; lcflag_t long c_cflag; lcflag_t long c_lflag; char c_line; cc_t char c_cc[NCCS]; }; The c_iflag field describes the basic terminal input con- trol. The following flags are defined by POSIX: 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. 4 April, 1990
termios(7P) termios(7P)ICRNL 0000400 Map CR to NL on input. IXON 0002000 Enable start/stop output control. IXOFF 0010000 Enable start/stop input control. In addition, A/UX supports the following flags:ICRNL 0000400 Map CR to NL on input.IUCLC 0001000 Map uppercase to lowercase on input.IXANY 0004000 Enable any character to restart output.If IGNBRK is set, a break condition detected on input is ig-nored; it is not put on the input queue and therefore notread by any process. If IGNBRK is not set and BRKINT isset, the break condition flushes both the input and outputqueues, and if the terminal is the controlling terminal of aforeground process group, a SIGINT signal is sent to thatforeground process group. If neither IGNBRK nor BRKINT isset, a break condition is read as a single `\0,' or ifPARMRK is set, as `\377,' `\0,' `\0.' If IGNPAR is set, abyte with a framing or parity error is ignored.If PARMRK is set and IGNPAR is not set, a byte with a fram-ing or parity is put on the input queue as the three-character sequence `\377,' `\0,' X, where `\377,' `\0,' is atwo-character flag and X is the data of the byte received inerror. To avoid ambiguity in this case, if ISTRIP is notset, a valid character of `\377' is given to the applicationas `\377,' `\377.' If neither PARMRK nor IGNPAR is set, aframing or parity error is put on the input queue as a sin-gle character, `\0.'If INPCK is set, input parity checking is enabled. If INPCKis not set, input parity checking is disabled, allowing out-put parity generation without input parity errors. Notethat whether input parity checking is enabled or disabled isindependent of whether parity detection is enabled or dis-abled. If parity detection is enabled but input paritychecking is disabled, the hardware to which the terminaldevice file is connected recognizes the parity bit, but theterminal special file does not check whether this bit is setcorrectly.If ISTRIP is set, valid input characters are first strippedto 7 bits; otherwise, all 8 bits are processed.If INLCR is set, a received newline (NL) character istranslated into a RETURN character. If IGNCR is set, a re-ceived RETURN character is ignored (not read). If ICRNL isset, a received RETURN character is translated in an NLcharacter.April, 1990 5
termios(7P) termios(7P)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 re- ceived STOP character suspends output and a received START character restarts output. All start/stop characters are not read, but perform flow-control functions. If IXANY is set, any input character restarts output that was suspended. If IXOFF is set, the system transmits START/STOP characters when the input queue is nearly empty or full. The initial input control value is all-bits-clear. The c_oflag field specifies the system treatment of output. POSIX defines the following flag for c_oflag:OPOST 0000001 Postprocess output.In addition, A/UX supports the following flags: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 Use NL to perform CR function. OFILL 0000100 Use fill characters for delay. OFDEL 0000200 Fill is DEL, else NNUL. NLDLY 0000400 Select newline delays: NL0 0 NL1 0000400 CRDLY 003000 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 VT1 0040000 FFDLY 0100000 Select form feed delays: FF0 0 FF1 0100000 If OPOST is set, output characters are postprocessed as in- dicated by the remaining flags; otherwise, characters are 6 April, 1990
termios(7P) termios(7P)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 carriage-return function, the column pointer are set to 0, and the delays specified for CR are used. Otherwise, the NL character is assumed to do just the line feed function; the column pointer remains unchanged. The column pointer is also set to 0 if the CR character is actually transmitted. The delay bits specify how long the transmission stops to allow for mechanical or other movement when certain charac- ters are sent to the terminal. In all cases a value of 0 indicates no delay. If OFILL is set, fill characters are transmitted for delay instead of a timed delay. This is useful for high-baud-rate terminals that need only a minimal delay. If OFDEL is set, the fill character is DEL, other- wise NUL. If a form feed delay or vertical tab delay is specified, it lasts for about 2 seconds. The newline delay lasts about 0.10 seconds. If ONLRET is set, the carriage-return delays are used instead of the new- line delays. If OFILL is set, two fill characters will be transmitted. The carriage-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 charac- ters. The 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 are transmitted for any delay. The backspace delay lasts about 0.05 seconds. If OFILL is set, one fill character is transmitted. The actual delays depend on line speed and system load. April, 1990 7
termios(7P) termios(7P)The initial output control value is all bits clear. The c_cflag field describes the hardware control of the ter- minal. POSIX defines the following flags: 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, else one. CREAD 0000200 Enable receiver. PARENB 0000400 Enable parity. PARODD 0001000 Odd parity, else even. HUPCL 0002000 Hang up on last close. CLOCAL 0004000 Local line, else dial-up. In addition, A/UX POSIX supports the following flags:LOBLK 0010000 Block layer output.CBAUD 0000017 Baud rate:B0 0 Hang upB50 0000001 50 baudB75 0000002 75 baudB110 0000003 110 baudB134 0000004 134.5 baudB150 0000005 150 baudB200 0000006 200 baudB300 0000007 300 baudB600 0000010 600 baudB1200 0000011 1200 baudB1800 0000012 1800 baudB2400 0000013 2400 baudB4800 0000014 4800 baudB9600 0000015 9600 baudB19200 0000016 19200 baudB38400 0000017 38400 baudEXTA 0000016 External AEXTB 0000017 External BThe CBAUD bits specify the baud rate. The zero baud rate,B0, is used to hang up the connection. If B0 is specified,the data-terminal-ready signal is not asserted. Normally,this disconnects the line. For any particular hardware, im-possible speed changes are ignored.The CSIZE bits specify the character size in bits for bothtransmission and reception. This size does not include theparity bit, if any. If CSTOPB is set, two stop bits areused, otherwise, one stop bit. For example, at 110 baud,two stops bits are required.8 April, 1990
termios(7P) termios(7P)If PARENB is set, parity generation and detection is en- abled, and a parity bit is added to each character. If par- ity 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 can be received. If HUPCL is set, the line is disconnected when the last pro- cess with the line open closes it or terminates. That is, the data-terminal-ready signal is not 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 is blocked when it is not the current layer. Otherwise, the output generated by that layer is 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 Enable canonical input (erase and kill processing). IEXTEN Enable extended functions. 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. TOSTOP 0100000 Send SIGTTOU for background output. In addition, A/UX provides:XCASE 0000004 Enable canonical uppercase andlowercase presentation.If ISIG is set, each input character is checked against thespecial control characters INTR, SUSP, SWTCH, and QUIT. Ifan 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 specialinput functions are possible only if ISIG is set. Thesefunctions may be disabled individually by changing the valueof the control character to an unlikely or impossible value,such as 0377.April, 1990 9
termios(7P) termios(7P)If ICANON is set, canonical processing is enabled. This en- ables the erase and kill edit functions as well as the as- sembly of input characters into lines delimited by NL, EOF, and EOL. If ICANON is not set, read requests are satisfied directly from the input queue. A read is not satisfied un- til at least MIN characters have been received or the timeout value TIME has expired between characters. This al- lows 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. There are currently no extended functions; therefore, the IEXTEN option has no effect. If XCASE is set and if ICANON is set, an uppercase letter is accepted on input by preceding it with a \ character and is output preceded by a \ character. In this mode, the follow- ing 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 possi- ble. If ECHO and ECHOE are set, the erase character is echoed as ASCII BS- SP- BS , which clears 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 is echoed after the kill character to em- phasize that the line is deleted. Note that an escape char- acter preceding the erase or kill character removes any spe- cial function. If ECHONL is set, the NL character is 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, suspend, switch, and inter- rupt characters is not done. 10 April, 1990
termios(7P) termios(7P)The initial line-discipline control value is all-bits-clear. The special characters with their default values and func- tions are as follows: INTR CONTROL-C. If the ISIG flag is enabled, generates a SIGINT signal that is sent to all processes in the distinguished process group associated with the ter- minal. QUIT ASCII FS. If the ISIG flag is enabled, generates a SIGQUIT signal that is sent to all processes in the distinguished process group associated with the ter- minal. ERASE DELETE. If the ICANON flag is set, erases the preceding character. It does not erase beyond the start of a line, as delimited by an NL, EOF, or EOL character. KILL CONTROL-U. If the ICANON flag is set, deletes the entire line, as delimited by an NL, EOF, or EOL char- acter. EOF CONTROL-D. If the ICANON flag is set when this char- acter is received, immediately pass to the program all the characters waiting to be read without waiting for a newline, and discard the EOF. If there are no characters waiting, zero characters are passed to the program to indicate an end-of-file condition. NL ASCII LF. If the ICANON flag is set, acts as the line delimiter (\n). It cannot be changed. EOL ASCII NUL. If the ICANON flag is set, acts as an ad- ditional line delimiter similar to NL . SUSP CONTROL-Z. If the ISIG flag is set, generates a SIGTSTP signal that is sent to all processes in the distinguished process group associated with the ter- minal. STOP CONTROL-S. If IXON or IXOFF flag is set, temporarily suspends output. This character is used on terminals to prevent output from disappearing before it can be read. START CONTROL-Q. If the IXON or IXOFF flag is set, resumes output that has been suspended by a STOP character. SWTCH CONTROL-Z. If used by the shell-layering facility, shl, changes the current layer to the control layer. April, 1990 11
termios(7P) termios(7P)The START and STOP characters cannot be changed. The values for INTR, QUIT, ERASE, KILL, EOF, EOL, and SUSP can be changed by using tcsetattr(3P). ERASE, KILL, and EOF char- acters may be escaped by preceding the character with a \; in this case, no special function is performed. c_line specifies the line discipline number for the termi- nal. The basic line discipline number is 0; this is currently the only line discipline supported. Special control characters are defined by the c_cc array in the termios structure. The subscript names and descriptions are as follows: VEOF EOF character VEOL EOL character VERASE ERASE character VINTR INTR character VKILL KILL character VQUIT QUIT character VSUSP SUSP character VMIN MIN character VTIME TIME character If a modem disconnect is detected by the terminal interface for a controlling terminal and if CLOCAL is not set in the c_cflag field for the terminal, a SIGHUP signal is sent to the controlling process associated with the terminal. Un- less other arrangements were made (see signal(3)), this causes the controlling process to terminate. Any subsequent read from the terminal device returns an end-of-line indica- tion until the device is closed. Thus, processes that read a terminal file and test for end-of-file can terminate ap- propriately after a disconnect. Any subsequent write(2) to the terminal device returns -1, with errno set to EI0, until the device is closed. The last process to close a terminal device file shall cause any output to be sent to the device and any input to be dis- carded. If HUPCL is set in the control structure and the communications port supports a disconnect function, the ter- minal device performs a disconnect. The following functions are provided for controlling the terminal interface: cfgetispeed(3P) Return the input baud rate. cfgetospeed(3P) Return the output baud rate. 12 April, 1990
termios(7P) termios(7P)cfsetispeed(3P) Set the input baud rate. cfsetospeed(3P) Set the output baud rate. tcdrain(3P) Wait until all written data is transmitted. tcflow(3P) Suspend or restart output or input. tcflush(3P) Discard data not transmitted. tcgetattr(3P) Get terminal attributes. tcgetpgrp(3P) Get distinguished process group ID. tcsendbreak(3P) Send a break. tcsetattr(3P) Set terminal attributes. tcsetpgrp(3P) Set distinguished process group ID. FILES /dev/tty SEE ALSO cfgetospeed(3P), fcntl(2), getty(1M), open(2), tcdrain(3P), tcgetpgrp(3p), tcgetattr(3P), tcsetpgrp(3P). April, 1990 13