[ Previous | Next | Contents | Glossary | Home | Search ]
AIX Version 4 Files Reference

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 General Programming Concepts: Writing and Debugging Programs.

Note: AIX 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:

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:

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.

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:

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:

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:

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:

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:

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:

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:

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 General Programming Concepts: Writing and Debugging Programs.

Implementation Specifics

This file is for Berkeley compatibility.

This file is part of Base Operating System (BOS) Runtime.

File

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

Related Information

The csh command, getty command, stty command, tset command.

The ioctl subroutine, sigvec subroutine.

tty Subsystem Overview in AIX General Programming Concepts: Writing and Debugging Programs.

[ Previous | Next | Contents | Glossary | Home | Search ]