sgtty.h File

Purpose

Provides the terminal interface for the Berkeley line discipline.

Description

The sgtty.h file defines the structures used by ioctl subroutines that apply to terminal files. The structures, definitions, and values in this file are provided for compatibility with the Berkeley user interface for asynchronous communication. Window and terminal size operations use the winsize structure, which is defined in the ioctl.h file. The winsize structure and the ioctl functions that use it are described in tty Subsystem Overview in AIX® Version 7.1 General Programming Concepts: Writing and Debugging Programs.

Note: Version 4 supports the Berkeley line discipline for compatibility with older applications. However, it is strongly recommended to use the POSIX compliant line discipline, which interface is described in the termios.h file.

Basic sgtty.h Modes

Basic ioctl functions use the sgttyb structure defined in the sgtty.h file. This structure contains the following fields:

sg_ispeed

Specifies the input speed of the device. For any particular hardware, impossible speed changes are ignored. Symbolic values in the table are as defined in the sgtty.h file.

B0: Hangs up. The zero baud rate is used to hang up the connection. If B0 is specified, the `data terminal ready' signal is dropped. As a result, the line is usually disconnected.
B50: 50 baud.
B75: 75 baud.
B110: 110 baud.
B134: 134.5 baud.
B150: 150 baud.
B200: 200 baud.
B300: 300 baud.
B600: 600 baud.
B1200: 1200 baud.
B1800: 1800 baud.
B2400: 2400 baud.
B4800: 4800 baud.
B9600: 9600 baud.
EXTA: External A.
EXTB: External B.

sg_ospeed

Specifies the output speed of the device. Refer to the description of the sg_ispeed field. The sg_ospeed field has the same values as the sg_ispeed field.

sg_erase

Specifies the erase character. (The default is Backspace.)

sg_kill

Specifies the kill character. (The default is Ctrl-U.)

sg_flags

Specifies how the system treats output. The initial output-control value is all bits clear. The possible output modes are:

ALLDELAY

Delays algorithm selection.

BSDELAY

Selects backspace delays. Backspace delays are currently ignored. Possible values are BS0 or BS1.

VTDELAY

Selects form-feed and vertical-tab delays:

FF0: Specifies no delay.
FF1: Specifies one delay of approximately 2 seconds.

CRDELAY

Selects carriage-return delays:

CR0: Specifies no delay.
CR1: Specifies one delay. The delay lasts approximately 0.08 seconds.
CR2: Specifies one delay. The delay lasts approximately 0.16 seconds.
CR3: Specifies one delay. The delay pads lines to be at least 9 characters at 9600 baud.

TBDELAY

Selects tab delays:

TAB0: Specifies no delay.
TAB1: Specifies one delay. The delay is dependent on the amount of movement.
TAB2: Specifies one delay. The delay lasts about 0.10 seconds.
XTABS: Specifies that tabs are to be replaced by the appropriate number of spaces on output.

NLDELAY

Selects the new-line character delays. This is a mask to use before comparing to NL0 and NL1.

NL0: Specifies no delay.
NL1: Specifies one delay. The delay is dependent on the current column.
NL2: Specifies one delay. The delay lasts about 0.10 seconds.

The delay bits specify how long transmission stops to allow for mechanical or other movement when certain characters are sent to the terminal. The actual delays depend on line speed and system load.

EVENP

Allows even parity on input.

The EVENP and ODDP flags control both parity checking on input and parity generation on output in COOKED and CBREAK mode (unless the LPASS8 bit is enabled). Even parity is generated on output unless the ODDP flag is set and the EVENP flag is clear, in which case odd parity is generated. Input characters with the wrong parity, as determined by the EVENP and ODDP flags, are ignored in COOKED and CBREAK mode.

ODDP

Allows odd parity on input. Refer to the description of the EVENP flag.

RAW

Indicates the RAW mode, which features a wake up on all characters and an 8-bit interface.

The RAW mode disables all processing except output flushing specified by the LFLUSHO bit. The full 8 bits of input are given as soon as they are available; all 8 bits are passed on output. A break condition in the input is reported as a null character. If the input queue overflows in RAW mode, all data in the input and output queues is discarded; this applies to both the new and old drivers.

CRMOD

Maps a carriage return into a new line on input and outputs a new line as a carriage return and a new line.

ECHO

Echo (full duplex).

LCASE

Maps uppercase to lowercase on input and lowercase to uppercase on output on uppercase terminals.

CBREAK

Enables a half-cooked mode. Programs can read each character as it is typed instead of waiting for a full line. All processing is done except input editing. Character and word erase, line kill, input reprint, and special treatment of the backslash character and the EOT character are disabled.

TANDEM

Enables automatic flow control (TANDEM mode), which causes the system to produce a stop character (Ctrl-S) when the input queue is in danger of overflowing, and a start character (Ctrl-Q) when the input queue has drained sufficiently. This mode is useful for flow control when the terminal is actually another computer that understands the conventions.

Note: The same stop and start characters are used for both directions of flow control. The character specified by the t_stopc field is accepted on input as the character that stops output and is produced on output as the character to stop input. The character specified by the t_startc field is accepted on input as the character that restarts output and is produced on output as the character to restart input.

Basic ioctl Operations

A large number of ioctl commands apply to terminals. Some have the general form:

#include <sgtty.h>
ioctl(FileDescriptor, Code, Value)
struct sgttyb *Value;

The applicable values for the Code parameter are:

Item	Description
TIOCGETP	Fetches the basic parameters associated with the terminal and stores them in the sgttyb structure that is pointed to.
TIOCSETP	Sets the parameters according to the sgttyb structure that is pointed to. The interface delays until output stops, then throws away any unread characters before changing the modes.
TIOCSETN	Has the same effect as the TIOCSETP value but does not delay or flush input. Input is not preserved, however, when changing to or from the RAW mode.

For the following codes, the Value parameter is ignored:

Item	Description
TIOCEXCL	Sets exclusive-use mode; no further opens are permitted until the file is closed.
TIOCNXCL	Turns off exclusive-use mode.
TIOCHPCL	When the file is closed for the last time, hangs up the terminal. This is useful when the line is associated with a modem used to place outgoing calls.

For the following code, the Value parameter is a pointer to an integer.

Item	Description
TIOCFLUSH	If the integer pointed to by the Value parameter has a zero value, all characters waiting in input or output queues are flushed. Otherwise, the value of the integer applies to the FREAD and FWRITE bits defined in the fcntl.h file. If the FREAD bit is set, all characters waiting in input queues are flushed. If the FWRITE bit is set, all characters waiting in output queues are flushed. Note: The FREAD and FWRITE bits cannot be used unless the _KERNEL flag is set.

Item

Description

TIOCFLUSH

If the integer pointed to by the Value parameter has a zero value, all characters waiting in input or output queues are flushed. Otherwise, the value of the integer applies to the FREAD and FWRITE bits defined in the fcntl.h file. If the FREAD bit is set, all characters waiting in input queues are flushed. If the FWRITE bit is set, all characters waiting in output queues are flushed.

Note: The FREAD and FWRITE bits cannot be used unless the _KERNEL flag is set.

In the following codes, the argument is 0 unless specified otherwise:

Item	Description
TIOCSTI	The Value parameter points to a character that the system pretends has been typed on the terminal.
TIOCSBRK	The break bit is set in the terminal.
TIOCCBRK	The break bit is cleared.
TIOCSDTR	Data terminal ready is set.
TIOCCDTR	Data terminal ready is cleared.
TIOCSTOP	Output is stopped as if the stop character had been typed.
TIOCSTART	Output is restarted as if the start character had been typed.
TIOCGPGRP	The Value parameter is a pointer to an integer into which is placed the process group ID of the process group for which this terminal is the control terminal.
TIOCSPGRP	The Value parameter is a pointer to an integer which is the value to which the process group ID for this terminal will be set.
TIOCOUTQ	Returns in the integer pointed to by the Value parameter the number of characters queued for output to the terminal.
TIONREAD	Returns in the integer pointed to by the Value parameter the number of characters immediately readable from the argument descriptor. This works for files, pipes, and terminals.

Uppercase Terminals

If the LCASE output-mode bit is set, all uppercase letters are mapped into the corresponding lowercase letter. The uppercase letter can be generated by preceding it with a \ (backslash). Uppercase letters are preceded by a backslash when they are output. In addition, the following escape sequences can be generated on output and accepted on input:

For	Use
` (grave)	\'
\|	\!
~	\^
{	\(
}	\)

To deal with terminals that do not understand that the ~ (tilde) has been made into an ASCII character, the LTILDE bit can be set in the local-mode word. When the LTILDE bit is set, the ~ (tilde) character will be replaced with the ` (grave) character on output.

Special Characters

A tchars structure associated with each terminal specifies special characters for both the old and new terminal interfaces. This structure is defined in the ioctl.h file, for which the sgtty.h file contains an #include statement. The tchars structure contains the following fields:

Item	Description
`t_intrc`	The interrupt character (Ctrl-C, by default) generates a SIGINT signal. This is the normal way to stop a process that is no longer needed or to regain control in an interactive program.
`t_quitc`	The quit character (Ctrl-\, by default) generates a SIGQUIT signal. This is used to end a program and produce a core image, if possible, in a core file in the current directory.
`t_startc`	The start-output character (Ctrl-Q, by default).
`t_stopc`	The stop-output character (Ctrl-S, by default).
`t_eofc`	The end-of-file character (Ctrl-D, by default).
`t_brkc`	The input delimiter (-1, by default). This character acts like a newline in that it ends a line, is echoed, and is passed to the program.

The stop and start characters can be the same to produce a toggle effect. The applicable ioctl functions are:

Item	Description
TIOCGETC	Gets the special characters and puts them in the specified structure.
TIOCSETC	Sets the special characters to those given in the structure.

Local Mode

Associated with each terminal is a local-mode word. The bits of the local-mode word are:

Item	Description
LCRTBS	Backspaces on erase rather than echoing erase.
LPRTERA	Printing terminal erase mode.
LCRTERA	Erases character echoes as Backspace-Space-Backspace.
LTILDE	Converts ~ (tilde) to ` (grave) on output (for terminals that do not recognize the tilde as an ASCII character).
LMDMBUF	Stops and starts output when carrier drops.
LLITOUT	Suppresses output translations.
LTOSTOP	Sends a SIGTTOU signal for background output.
LFLUSHO	Output is being flushed.
LNOHANG	Do not send hang up when carrier drops.
LCRTKIL	Backspace-Space-Backspace to erase the entire line on line kill.
LPASS8	Passes all 8 bits through on input, in any mode.
LCTLECH	Echoes input control characters as Ctrl-X, delete as Ctrl-?.
LPENDIN	Retypes pending input at next read or input character.
LDECCTQ	Only Ctrl-Q restarts output after a Ctrl-S.
LNOFLSH	Inhibits flushing of pending I/O when an interrupt character is typed.

The following ioctl functions operate on the local-mode word structure:

Item	Description
TIOCLBIS	The Value parameter is a pointer to an integer whose value is a mask containing the bits to be set in the local-mode word.
TIOCLBIC	The Value parameter is a pointer to an integer whose value is a mask containing the bits to be cleared in the local-mode word.
TIOCLSET	The Value parameter is a pointer to an integer whose value is stored in the local-mode word.
TIOCLGET	The Value parameter is a pointer to an integer into which the current local-mode word is placed.

Local Special Characters

The ltchars structure associated with each terminal defines control characters for the new terminal driver. This structure contains the following fields:

Item	Description
`t_suspc`	The suspend-process character (Ctrl-Z, by default). This sends a SIGTSTP signal to suspend the current process group. This character is recognized during input.
`t_dsuspc`	The delayed suspend-process character (Ctrl-Y, by default). This sends a SIGTSTP signal to suspend the current process group. This character is recognized when the process attempts to read the control character rather than when the character is typed.
`t_rprntc`	The reprint line-control character (Ctrl-R, by default). This reprints all characters that are preceded by a new-line character and have not been read.
`t_flushc`	The flush-output character (Ctrl-O, by default). This flushes data that is written but not transmitted.
`t_werasc`	The word-erase character (Ctrl-W, by default). This erases the preceding word. This does not erase beyond the beginning of the line.
`t_lnextc`	The literal-next character (Ctrl-V, by default). This causes the special meaning of the next character to be ignored so that characters can be input without being interpreted by the system.

The following ioctl functions, which use the ltchars structure, are supported by the terminal interface for the definition of local special characters for a terminal:

Item	Description
TIOCSLTC	Sets local characters. The argument to this function is a pointer to an ltchars structure, which defines the new local special characters.
TIOCGLTC	Sets local characters. The argument to this function is a pointer to an ltchars structure into which is placed the current set of local special characters.

The winsize structure and the ioctl functions that use it are described in the discussion of the tty common code in "tty Subsystem Overview" in AIX Version 7.1 General Programming Concepts: Writing and Debugging Programs.

File

Item	Description
/dev/tty	The tty special file, which is a synonym for the controlling terminal.