NAME

termio − general terminal interface

DESCRIPTION

All of the asynchronous communications ports use the same general interface, no matter what hardware is involved.  The remainder of this section discusses the common features of this interface. 

Opening a Terminal File

When a terminal file is opened, it normally causes the process to wait until a connection is established.  In practice, users’ programs seldom open these files; they are opened by getty and become a user’s standard input, output, and error files.  When a process group leader without a controlling terminal opens a terminal that is not already a controlling terminal, that terminal becomes the controlling terminal for that process and the terminal’s distinguished process group (tty group ID) is set to the process group of that process. The control terminal plays a special role in handling QUIT and INTERRUPT signals, as discussed below. It is also used in handling the process group control signals. The control terminal is inherited by a child process during a fork(2). A process can break this association by changing its process group using setpgrp(2). When the process group leader that acquired the controlling terminal terminates, the distinguished process group of the controlling terminal is set to zero (indicating no distinguished process group). This allows the terminal to be acquired as a controlling terminal by a new process group leader.

If the O_NDELAY bit (see open(2)) is clear, an open will block until the type of modem connection requested (see modem(7)) is completed. If the O_NDELAY bit is set, an open will succeed and return immediately without waiting for the modem connection requested to complete. 

Reading Characters

A terminal associated with one of these files ordinarily operates in full-duplex mode.  Characters may be typed at any time, even while output is occurring, and are only lost when the system’s character input buffers become completely full, which is rare, or when the user has accumulated the maximum allowed number of input characters that have not yet been read by some program.  This limit is dependent on the particular implementation, but is at least 256.  When the input limit is reached, all the saved characters are thrown away without notice. 

Canonical Mode Input Processing (Erase and Kill Processing)

Normally, terminal input is processed in units of lines.  A line is delimited by a new-line (ASCII LF) character, an end-of-file (ASCII EOT) character, or an end-of-line character.  This means that a program attempting to read will be suspended until an entire line has been typed.  Also, 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. 

During input, erase and kill processing is normally done.  By default, the character # erases the last character typed, except that it will not erase beyond the beginning of the line.  By default, the character @ kills (deletes) the entire input line, and optionally outputs a new-line character.  Both these characters operate on a key-stroke basis, independently of any backspacing or tabbing that may have been done.  Both the erase and kill characters may be entered literally by preceding them with the escape character (\).  In this case the escape character is not read.  The erase and kill characters may be changed. 

Process Group Control During I/O

For those drivers that support process group control, if a process is not in the distinguished process group of its control terminal, and both the process group of the process and the control terminal are non-zero, the process is said to be a background process. Any attempts by a background process to read from its controlling terminal will cause the process group to be sent a SIGTTIN signal, which will normally cause the members of that process group to stop.  If, however, a process is ignoring or holding the SIGTTIN signal, or (on systems that implement vfork separately from fork) has made a call to vfork(2) but not yet made a call to exec(2), then the process is instead returned an EIO error and no signal is sent to any process.

It is frequently undesirable for background processes to write to a terminal.  If the LTOSTOP bit is set, a background process is prohibited from writing to that terminal.  Attempts to write cause the process group to be sent a SIGTTOU signal, which normally causes the members of the process group to stop.  If the LTOSTOP bit is not set, the process is ignoring or holding SIGTTOU signals, or is in the middle of the vfork(2) window described above, and the process is allowed to write to the terminal. Certain ioctl system calls that set tty parameters are treated in this same fashion, except that the setting of the LTOSTOP bit is ignored.  The effect is identical to that of terminal writes when the LTOSTOP bit is set. 

Non-blocking Reads (O_NDELAY Flag)

If the O_NDELAY bit (see open(2) or fcntl(2)) is clear, the read request will complete whenever data is available. If the O_NDELAY bit is set, then the read request will complete, without blocking, in one of three ways: (1) If there is enough data available to satisfy the entire request, the read will complete successfully, having read all of the data, and return the number of bytes read; (2) If there is not enough data available to satisfy the entire request, the read will complete successfully, having read as much data as possible, and return the number of bytes it was able to read; (3) If there is no data available, the read will complete successfully, having read no data, and return a count of 0.

Special Characters

Certain characters have special functions on input.  These functions and their default character values are summarized as follows:

INTR (Rubout or ASCII DEL) generates an interrupt signal, which is sent to all processes with the associated control terminal.  Normally, each such process is forced to terminate, but arrangements may be made either to ignore the signal or to receive a trap to an agreed-upon location; see signal(2).

QUIT (Control-│ or ASCII FS) generates a quit signal.  Its treatment is identical to the interrupt signal except that, unless a receiving process has made other arrangements, it will not only be terminated but a core image file (called core) will be created in the current working directory if the implementation supports core files. 

SWTCH (ASCII NUL) is only used by the shell layers facility shl(1). The shell layers facility is not part of the general terminal interface.  No special functions are performed by the general terminal interface when SWTCH characters are encountered.

ERASE (#) erases the preceding character.  It will not erase beyond the start of a line, as delimited by a NL, EOF, or EOL character. 

KILL (@) deletes the entire line, as delimited by a NL, EOF, or EOL character. 

EOF (Control-d or ASCII EOT) may be used to generate an end-of-file from a terminal.  When received, all the characters waiting to be read are immediately passed to the program, without waiting for a new-line, and the EOF is discarded.  Thus, if there are no characters waiting, which is to say the EOF occurred at the beginning of a line, zero characters will be passed back, which is the standard end-of-file indication. 

NL (ASCII LF) is the normal line delimiter.  It cannot be changed or escaped. 

EOL (ASCII NUL) is an additional line delimiter, like NL.  It is not normally used. 

STOP (Control-s or ASCII DC3) can be used to temporarily suspend output.  It is useful with CRT terminals to prevent output from disappearing before it can be read.  While output is suspended, STOP characters are ignored and not read. 

START (Control-q or ASCII DC1) is used to resume output that has been 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. 

The character values for INTR, QUIT, ERASE, KILL, EOF, SWTCH, and EOL may be changed to suit individual tastes.  The ERASE, KILL, and EOF characters may be escaped by a preceding \ character, in which case no special function is done. 

Writing Characters

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. 

Closing a Terminal File

When the last process to have a terminal device file open closes the file, the output data is drained before the close returns. 

Modem Disconnect

When a modem disconnect is detected, a hang-up signal is sent to all processes that have this terminal as the control terminal.  Unless other arrangements have been made, this signal causes the processes to terminate.  If the hang-up signal is ignored, any subsequent read returns 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. 

Termio Structure

Several ioctl(2) system calls apply to terminal files. The primary calls use the following structure, defined in <termio.h>:

#define NCC

8

structtermio {

	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 ∗/

};

The special control characters are defined by the array c_cc. The relative positions and initial values for each function are as follows:

0VINTRDEL
1VQUITFS
2VERASE#
3VKILL@
4VEOFEOT
5VEOLNUL
6reserved
7VSWTCH NUL

Input Modes

The c_iflag field describes the basic terminal input control:

IGNBRK0000001Ignore break condition.
BRKINT0000002Signal interrupt on break.
IGNPAR0000004Ignore characters with parity errors.
PARMRK0000010Mark parity errors.
INPCK0000020Enable input parity check.
ISTRIP0000040Strip character.
INLCR0000100Map NL to CR on input.
IGNCR0000200Ignore CR.
ICRNL0000400Map CR to NL on input.
IUCLC0001000Map uppercase to lowercase on input.
IXON0002000Enable start/stop output control.
IXANY0004000Enable any character to restart output.
IXOFF0010000Enable start/stop input control.
IENQAK0020000Enable output pacing control.

If IGNBRK is set, the break condition (a character framing error with data all zeros) is ignored, that is, not put on 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 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. 

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 CR character.  If IGNCR is set, a received CR character is ignored (not read).  Otherwise if ICRNL is set, a received CR 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 that has been suspended. 

If IXOFF is set, start/stop input control is enabled.  When the number of characters in the input queue exceeds a system defined value (high water mark), the system will transmit a STOP character.  This should cause the attached device to stop transmitting data before the maximum allowed input has been reached.  When enough characters have been read from the input queue that the number of remaining characters is less than another system defined value (low water mark), then the system will transmit a START character to cause input to be resumed.  In order to avoid potential deadlock, the IXOFF bit is ignored in canonical mode whenever there is no line delimiter in the input buffer.  In this case, the STOP character is not sent at the high water mark, but will be transmitted later if a delimiter is received.  If all complete lines are read from the input queue leaving only a partial line with no line delimiter, the START character will be sent even though the number of characters may not be less than the low water mark.  When ICANON is set and the input stream contains more characters between line delimiters than the high water mark allows, it is not guaranteed that IXOFF will prevent buffer overflow and data loss, since the STOP character may not be sent in time or at all. 

If IENQAK is set, the system will transmit ASCII ENQ after every 80 characters sent and then wait until the terminal responds with ASCII ACK.  The terminal will respond in this way when it has sufficiently emptied its buffer.  If the terminal does not respond after 5 seconds, the system will resume transmission anyway.  The ASCII ACK that the terminal sends will not get entered into the input queue if it was sent in response to ASCII ENQ. 

The initial input control value is all-bits-clear. 

Output Modes

The c_oflag field specifies the system treatment of output:

OPOST0000001Postprocess output.
OLCUC0000002Map lowercase to uppercase on output.
ONLCR0000004Map NL to CR-NL on output.
OCRNL0000010Map CR to NL on output.
ONOCR0000020No CR output at column 0.
ONLRET0000040NL performs CR function.
OFILL0000100Use fill characters for delay.
OFDEL0000200Fill is DEL, else NUL.
NLDLY0000400Select new-line delays:
NL00
NL10000400
CRDLY0003000Select carriage-return delays:
CR00
CR10001000
CR20002000
CR30003000
TABDLY0014000Select horizontal-tab delays:
TAB00
TAB10004000
TAB20010000
TAB30014000Expand tabs to spaces.
BSDLY0020000Select backspace delays:
BS00
BS10020000
VTDLY0040000Select vertical-tab delays:
VT00
VT10040000
FFDLY0100000Select form-feed delays:
FF00
FF10100000

If OPOST is set, output characters are post-processed 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 carriage-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 a timed delay.  This is useful for high baud rate 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. 

New-line 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. 

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 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. 

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. 

Control Modes

The c_cflag field describes the hardware control of the terminal:

CBAUD0000037Baud rate:
B00Hang up
B50000000150 baud
B75000000275 baud
B1100000003110 baud
B1340000004134.5 baud
B1500000005150 baud
B2000000006200 baud
B3000000007300 baud
B6000000010600 baud
B9000000011900 baud
B120000000121200 baud
B180000000131800 baud
B240000000142400 baud
B360000000153600 baud
B480000000164800 baud
B720000000177200 baud
B960000000209600 baud
B19200000002119200 baud
B38400000002238400 baud
EXTA0000036External A
EXTB0000037External B
CSIZE0000140Character size:
CS505 bits
CS600000406 bits
CS700001007 bits
CS800001408 bits
CSTOPB0000200Send two stop bits, else one.
CREAD0000400Enable receiver.
PARENB0001000Parity enable.
PARODD0002000Odd parity, else even.
HUPCL0004000Hang up on last close.
CLOCAL0010000Local line, else dial-up.
LOBLK0020000Reserved for use by shl(1).

The CBAUD bits specify the baud rate.  The zero baud rate, B0, is used to hang up the connection.  If B0 is specified, the modem control lines (see modem(7)) will cease to 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 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. 

The specific effects of the HUPCL and CLOCAL bits depend on the mode and type of the modem control in effect.  See modem(7) for the details.

If HUPCL is set, the modem control lines for the port will be disconnected when the last process with the port open closes it or terminates. 

If CLOCAL is set, a connection does not depend on the state of the modem status lines. 

If the CLOCAL bit has been set, an open will return immediately without waiting for the connection.  For those files on which the connection has not been established or has been lost, and for which the CLOCAL bit is not set, both read and write will return a zero character count.  For read, this is equivalent to an end-of-file condition.

The initial hardware control value after open is B300, CS8, CREAD, HUPCL. 

LOBLK is used by the shell layers facility (see shl(1)). The shell layers facility is not part of the general terminal interface, and the LOBLK bit is not examined by the general terminal interface. 

Local Modes

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:

ISIG0000001Enable signals.
ICANON0000002Canonical input (erase and kill processing).
XCASE0000004Canonical upper/lower presentation.
ECHO0000010Enable echo.
ECHOE0000020Echo erase character as BS-SP-BS.
ECHOK0000040Echo NL after kill character.
ECHONL0000100Echo NL.
NOFLSH0000200Disable flush after interrupt, quit, or suspend.

If ISIG is set, each input character is checked against the special control characters INTR, QUIT, and the suspend characters (see Process Group Control below).  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 (e.g., 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 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.  (See Non-canonical Mode Input Processing (MIN/TIME Interaction) below).  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 is output 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, interrupt, and suspend characters will not be done. 

The initial line-discipline control value is all bits clear. 

Unless otherwise noted for a specific ioctl command, the ioctls are restricted from use by background processes. An attempt to issue an ioctl from a background process will cause the process to block and may cause a SIGTTOU signal to be sent to the process group. 

Non-canonical Mode Input Processing (MIN/TIME Interaction)

The MIN and TIME values are stored in c_cc[VMIN] and c_cc[VTIME], respectively, and are used when ICANON is clear.  MIN represents the minimum number of characters that should be received when the read is satisfied (i.e., the characters are returned to the user).  TIME is a timer of 0.10 second granularity that is used to timeout burst and short term data transmissions.  The four possible values for MIN and TIME and their interactions are described below. 
 
A. MIN > 0, TIME > 0 In this case TIME serves as an intercharacter timer and is activated after the first character is received.  Since it is an intercharacter timer, it is reset after a character is received.  The interaction between MIN and TIME is as follows: as soon as one character is received, the intercharacter timer is started.  If MIN characters are received before the intercharacter timer expires (remember that the timer is reset upon receipt of each character), the read is satisfied.  If the timer expires before MIN characters are received, the characters received to that point are returned to the user.  Note that if TIME expires, at least one character will be returned because the timer would not have been enabled unless a character was received.  In this case ( MIN > 0, TIME > 0 ) the read will sleep until the MIN and TIME mechanisms are activated by the receipt of the first character.  B. MIN > 0, TIME = 0 In this case, since the value of TIME is zero, the timer plays no role and only MIN is significant.  A pending read is not satisfied until MIN characters are received after any previous read completes (i.e., the pending read will sleep until MIN characters are received).  A program that uses this case to handle record-based terminal I/O may block.  C. MIN = 0, TIME > 0 In this case, since MIN = 0, TIME no longer represents an intercharacter timer.  It now serves as a read timer that is activated as soon as the read system call is processed.  A read is satisfied as soon as a single character is received or the read timer expires.  Note that in this case, if the timer expires, no character will be returned.  If the timer does not expire, the only way the read can be satisfied is if a character is received.  Note that in this case the read will not sleep indefinitely waiting for a character.  If no character is received within TIME * 0.10 seconds after the read is initiated, the read will return with zero characters.  D. MIN = 0, TIME = 0 In this case return is immediate. If characters are present, they will be returned to the user.

Some points to note about MIN and TIME:

1.  In the above explanations one may notice that the interactions of MIN and TIME are not symmetric. For example, when MIN > 0 and TIME = 0, TIME has no effect.  However, in the opposite case where MIN = 0 and TIME > 0, both MIN and TIME play a role in that MIN is satisfied with the receipt of a single character. 

2.  Also note that in case A ( MIN > 0, TIME > 0 ), TIME represents an intercharacter timer while in case C ( MIN = 0, TIME > 0 ), TIME represents a read timer. 

These two points highlight the dual purpose of the MIN/TIME feature.  Cases A and B, where MIN > 0, exist to handle burst mode activity (e.g., file transfer programs) where a program would like to process at least MIN characters at a time.  In case A, the intercharacter timer is activated by a user as a safety measure while in case B it is turned off. 

Cases C and D exist to handle single character timed transfers.  These cases are readily adaptable to screen based applications that need to know if a character is present in the input queue before refreshing the screen. In case C the read is timed, while in case D it is not. 

Another important note is that MIN is always just a minimum.  It does not denote a record length.  That is, if a program does a read of 20 bytes and MIN is 10 and 25 characters are present, 20 characters will be returned to the user.  If the program had requested all characters, then all 25 characters would be returned to the user. 

Primary TERMIO IOCTL Commands

The primary ioctl(2) system calls have the form:

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. This command is allowed from a background process; however, the information may be subsequently changed by a foreground process.

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, then 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 at least 0.25 seconds). 

TCXONC Start/stop control.  If arg is 0, suspend output; if 1, restart suspended output. 

TCFLSH If arg is 0, flush the input queue; if 1, flush the output queue; if 2, flush both the input and output queues. 

The following command has the form:

ioctl (fildes, command, arg)
long *arg;

FIONREAD Returns in the long integer whose address is arg the number of characters immediately readable from the terminal device file.  This command is allowed from a background process; however, the data itself may not be read from a background process. 

System Asynchronous I/O

The following commands have the form:

ioctl (fildes, command, arg)
int *arg;

FIOSSAIOSTAT If the integer whose address is arg is non-zero, system asynchronous I/O is enabled.  That is, enable SIGIO to be sent to the process currently designated with FIOSSAIOOWN (see below) whenever the terminal device file status changes from "no read data available" to "read data available".  If no process has been designated with FIOSSAIOOWN, then enable SIGIO to be sent to the first process to open the terminal device file.  If the designated process has exited, the SIGIO signal will not be sent to any process. If the integer whose address is arg is 0, system asynchronous I/O is disabled. 

FIOGSAIOSTAT The integer whose address is arg is set to 1, if system asynchronous I/O is enabled.  Otherwise, the integer whose address is arg is set to 0. 

FIOSSAIOOWN Set process ID to receive the SIGIO signals with system asynchronous I/O to the value of the integer whose address is arg.  The super-user may designate that any process receive the SIGIO signals.  If the request is not made by the super-user, the calling process is only allowed to designate that itself or another process whose real or saved effective user ID matches its real or effective user ID, or a process that is a descendant of the calling process, receive the SIGIO signals.  If no process can be found corresponding to that specified by the integer whose address is arg, the call will fail, with errno set to ESRCH.  If the request is not made by the super-user, and the calling process attempts to designate a process other than itself or another process whose real or saved effective user ID matches its real or effective user ID, or a process that is not a descendant of the calling process, the call will fail, with errno set to EPERM.  If the designated process subsequently exits, the SIGIO signal will not be sent to any process. The default on open of a terminal device file is that the process performing the open is set to receive the SIGIO signals.

FIOGSAIOOWN The integer whose address is arg is set to the process ID designated to receive SIGIO signals. 

Non-blocking I/O

FIOSNBIO
If the integer whose address is arg is non-zero, non-blocking I/O is enabled.  That is, subsequent reads and writes to the terminal device file will be handled in a non-blocking manner (see below).  If the integer whose address is arg is 0, non-blocking I/O is disabled.  For reads, non-blocking I/O will prevent all read requests to that device file from blocking, whether the requests succeed or fail. Such a read request will complete in one of three ways: (1) If there is enough data available to satisfy the entire request, the read will complete successfully, having read all of the data, and return the number of bytes read; (2) If there is not enough data available to satisfy the entire request, the read will complete successfully, having read as much data as possible, and return the number of bytes it was able to read; (3) If there is no data available, the read will fail and errno will be set to EWOULDBLOCK.  For writes, non-blocking I/O will prevent all write requests to that device file from blocking, whether the requests succeed or fail. Such a write request will complete in one of three ways: (1) If there is enough space available in the system to buffer all the data, the write will complete successfully, having written out all of the data, and return the number of bytes written; (2) If there is not enough space in the buffer to write out the entire request, the write will complete successfully, having written as much data as possible, and return the number of bytes it was able to write; (3) If there is no space in the buffer, the write will fail and errno will be set to EWOULDBLOCK.  To prohibit non-blocking I/O from interfering with the O_NDELAY flag (see open(2) and fcntl(2)), the functionality of O_NDELAY always supercedes the functionality of non-blocking I/O. This means that if O_NDELAY is set, the driver will perform read requests in accordance with the definition of O_NDELAY. When O_NDELAY is not set, the definition of non-blocking I/O applies. The default on open of a terminal device file is that non-blocking I/O is disabled.

FIOGNBIO
The integer whose address is arg is set to 1, if non-blocking I/O is enabled.  Otherwise, the integer whose address is arg is set to 0. 

Process Group Control

Some implementations support process group control.  The following structure, used with process group control, is defined in <bsdtty.h>:

struct	ltchars	{
	unsigned char	t_suspc;	/∗ stop process character ∗/
	unsigned char	t_dsuspc;	/∗ delayed stop process character ∗/
	unsigned char	t_rprntc;	/∗ reserved; must be 0377 ∗/
	unsigned char	t_flushc;	/∗ reserved; must be 0377 ∗/
	unsigned char	t_werasc;	/∗ reserved; must be 0377 ∗/
	unsigned char	t_lnextc;	/∗ reserved; must be 0377 ∗/
};

The initial value for all these characters is 0377, which causes them to be disabled.  The meaning for each character is as follows:

t_suspc is used to suspend the currently active process group.  A suspend signal (SIGTSTP) is sent to all processses in the currently active process group.  Normally, each process is forced to stop, but arrangements may be made either to ignore the signal or to receive a trap to an agreed-upon location; see signal(2). When enabled, the typical value for this character is control-z or ASCII SUB. 

t_dsuspc functions like t_suspc, except that the suspend signal is sent when a process reads the character rather than when it is typed.  When enabled, the typical value for this character is control-y or ASCII EM. 

Attempts to set any of the reserved characters to a value other than 0377 will cause the ioctl to be returned with an EINVAL error code and no change will occur. 

The ioctl(2) system calls that use the above structure have the form:

ioctl (fildes, command, arg)
struct ltchars ∗arg;

The commands using this form are:

TIOCGLTC Get the process group control characters and store in the ltchars structure whose address is arg. This command is allowed from a background process; however, the information may be subsequently changed by a foreground process.

TIOCSLTC Set the process group control characters from the structure whose address is arg.

Additional process group control ioctl(2) commands have the form:

ioctl (fildes, command, arg)
unsigned int ∗arg;

The commands using this form are:

TIOCGPGRP Returns in the integer whose address is arg the currently active process group associated with the terminal.  This command is allowed from a background process; however, the information may be subsequently changed by a foreground process. 

TIOCSPGRP Sets the currently active process group associated with the terminal to be the one whose address is arg.

The following condition must be met for the request to succeed; otherwise, the error [EINVAL] is returned:

The new process group value must be in the range of valid process group ID values, or it must be zero ("no process group"). 

One or more of the following conditions must be met for the request to succeed; otherwise, the error [EPERM] is returned:

The effective user ID of the current process is super-user. 

The process group ID whose address is arg matches the saved process group ID of the calling process. 

If any processes exist with a process ID or process group ID that is the same as the process group whose address is arg, those processes must have the same real or saved user ID as the real or effective user ID of the calling process, or be descendants of the calling process. 

TIOCLGET Get the process group control mode word and store in the int pointed to by arg. This command is allowed from a background process; however, the information may be subsequently changed by a foreground process.

TIOCLSET Set the process group control mode word from the int pointed to by arg.

TIOCLBIS Use the int pointed to by arg as a mask of bits to set in the process group control mode word. 

TIOCLBIC Use the int pointed to by arg as a mask of bits to clear in the process group control mode word. 

The following bit is defined in the process group control mode word:

LTOSTOP

Send SIGTTOU for background write.

If the LTOSTOP bit is set, an attempt by a process that is not in the distinguished process group to write data causes a SIGTTOU signal to be sent to that process group. 

WARNINGS

Because various HP-UX implementations use non-serial interfaces that look like terminals (e.g., internal CRT’s) or "smart cards," which cannot implement the capabilities described above exactly, not all the systems can exactly meet the standard stated above.  Each implementation is required to state any deviations from the standard as part of its system specific documentation. 

FIOSSAIOSTAT is similar to 4.2 BSD FIOASYNC, with the addition of provisions for security.  FIOGSAIOSTAT is of HP origin, complements FIOSSAIOSTAT, and allows saving and restoring system asynchronous I/O TTY state for BSD style job control.  FIOSSAIOOWN is similar to 4.2 BSD FIOSETOWN, with the addition of provisions for security.  FIOGSAIOOWN is similar to 4.2 BSD FIOGETOWN.  Note also the difference that the 4.2 BSD version of this functionality used process groups, while the HPUX version only uses processes.  FIOSNBIO is the same as 4.2 BSD FIONBIO, except that it does not interfere with the ATT O_NDELAY open and fcntl flag.  FIOGNBIO is of HP origin, complements FIOSNBIO, and allows saving and restoring non-blocking I/O TTY state for BSD style job control. 

HARDWARE DEPENDENCIES

Series 200, 300
Data loss may occur with HP 98626/98644 serial interfaces if the effective combined data rate for all installed serial interfaces exceeds 2400 baud (for example, two interfaces running at 1200 baud and a third at 300 baud is equivalent to 2700 baud combined).
The c_iflag field parameter IXANY (enable any character to restart output) is not supported by the HP 98628B interface card. 
The c_iflag field parameter IENQAK (enable output pacing control) is not supported. 
Timed delays are not supported.
The HP 98628B interface does not support the following baud rates: 900, 7200, 38400.
The FIONREAD ioctl command is not supported. 
The c_lflag field parameter XCASE is not supported. 

Series 200, 300, 500
The features described under System Asynchronous I/O, Non-blocking I/O, and Process Group Control are not supported. 

For the purposes of Process Group Control During I/O, all processes are considered to be foreground processes at all times. 

Series 500
The baud rate of 38400 is not supported by the RS-232 interface.

HP27140 Six-Channel Modem Multiplexer:
Timed output delays (as opposed to fill-character delays) are not supported.

The XCASE flag is not supported. 

These baud rates are not supported: 200, 38400, EXTA, and EXTB. 

HP27128 Asynchronous Serial Interface, HP27130 Eight-Channel Multiplexer:
These baud rates are not supported: 200, 38400, EXTA, and EXTB. 

There is no support for tab expansion, case mapping, or output delays for control characters. 

The line kill character is always echoes as <backslash><CR><LF>, so the ECHOK flag is not setable, and will always have the same state as the ECHO flag. 

When type-ahead limit is reached, input is not flushed, but further input is simply ignored. 

The PARMRK flag is not supported. 

The echoing of carriage-return and new-line characters may not be quite as expected in the more obscure driver configurations. 

The echoing of the EOF character is not suppressed. 

The ONLRET, ONOCR, and OCRNL flags are not supported. 

The VMIN and VTIME parameters for raw terminal input are not supported. 

The ECHONL flag is not supported. 

When ECHOE is set and ECHO is clear, a <SP><BS> is not echoes for the erase character. 

(27130 only) The CLOCAL flag is permanently set. 

(27128 only) The default setting of baud rate, bits per character, parity, and CLOCAL bit are determined by the switches on the interface. 

(27128 only) The "direct connect" cable (female connector) does not contain a Data Carrier Detect line, so a hangup signal will be sent if the CLOCAL flag is cleared when this cable is being used. 

Model 520 Console, HP98700 Terminal, Pseudo Terminal (pty): Since these devices do not deal with real asynchronous serial data links, the following flags have no effect: IGNPAR, PARMRK, INPCK, IXOFF, IENQAK, CBAUD, CSIZE, CSTOPB, PARENB, PARODD, HUPCL, and CLOCAL. 

Series 800
ENQ/ACK protocol and IENQAK bit are not supported. Timed output delays are not directly supported.  If used, an appropriate number of fill characters (based on the current baud rate) is output.  The total time to output the fill characters is at least as long as the time requested. The baud rate of 38400 is not supported by the RS-232 interface. The system specified input flow control values are as follows: low water mark is 60, high water mark is 180, and maximum allowed input is 512. Shell layers is not supported.  Therefore, neither the special character SWTCH nor the control mode LOBLK is supported. 

AUTHOR

Termio was developed by HP, AT&T, and the University of California,

FILES

/dev/console
/dev/tty∗

SEE ALSO

mknod(1M), shl(1), stty(1), fork(2), ioctl(2), setpgrp(2), signal(2), stty(2), blmode(3C), sttyV6(7), tty(7), modem(7). 

Hewlett-Packard Company  —  Version B.1,  May 11, 2021