COHERENT manpages
This page displays the COHERENT manpage for sgtty [General terminal interface].
List of available manpages
Index
sgtty -- Device Driver
General terminal interface
COHERENT uses two method for controlling terminals: sgtty and termio. To
use sgtty, simply include the statement #include <sgtty.h> in your
sources. To use termio, include the statement #include <termio.h>.
The rest of this article discusses the sgtty method of controlling
terminals.
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 the program getty and become a user's
standard input, output, and error files. The very first terminal file
opened by the process group leader of a terminal file not already
associated with a process group becomes the controlling terminal for that
process group. The controlling terminal plays a special role in handling
quit and interrupt signals, as discussed below. The controlling terminal
is inherited by a child process during a call to fork. A process can break
this association by changing its process group using setpgrp.
A terminal associated with one of these files ordinarily operates in full-
duplex mode. Characters can be typed at any time, even while output is
occurring, and are only lost when the system's 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. Currently, this limit is 256 characters. When the input
limit is reached, the sytems throws away all the saved characters without
notice.
Normally, terminal input is processed in units of lines. A line is
delimited by a newline character (ASCII LF) or an end-of-file character
(ASCII EOT). Unless otherwise directed, 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, the system normally processes erase and kill characters. By
default, the backspace character erases the last character typed, except
that it will not erase beyond the beginning of the line. By default, the
<ctrl-U> kills (deletes) the entire input line, and optionally
outputs a newline character. Both these characters operate on a keystroke-
by-keystroke basis, independently of any backspacing or tabbing which 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. You may change the erase and kill
characters via command stty.
Certain characters have special functions on input. These functions and
their default character values are summarized as follows:
INTR (<ctrl-C> or ASCII ETX) generates an interrupt signal that
is sent to all processes associated with the controlling
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 the Lexicon entry
for signal.
QUIT (Control-\ or ASCII ES) generates a quit signal. Its treatment
is identical to that of 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.
ERASE (<backspace> or ASCII BS) erases the preceding character.
It will not erase beyond the start of a line, as delimited by a
newline or EOF character.
KILL (<ctrl-U> or ASCII NAK) deletes the entire line, as
delimited by a newline or EOF character.
EOF (<ctrl-D> or ASCII EOT) generates an end-of-file character
from a terminal. When received, all the characters waiting to be
read are immediately passed to the program without waiting for a
newline, and the EOF is discarded. Thus, if no characters are
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.
STOP (<ctrl-S> or ASCII DC3) can be used to 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 (<ctrl-Q> or ASCII DC1) resumes 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 can be changed via command stty, or via special
ioctl() calls described below.
The character values for INTR, QUIT, ERASE, EOF, and KILL may be changed to
suit individual tastes. The ERASE, KILL, and EOF character may be escaped
by a preceding \ character, in which case the system ignores its special
meaning. See the Lexicon article on stty for information on how to change
these settings dynamically.
When using a ``modem control'' serial line, loss of carrier from the data-
set (modem) causes a hangup signal to be sent to all processes that have
this terminal as the controlling terminal. Unless other arrangements have
been made, this signal causes the process to terminate. If the hangup
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.
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 into the output queue as they
arrive. If a process produces characters more rapidly than they can be
printed, it will be suspended when its output queue exceeds some limit,
known as the ``high water mark''. When the queue has ``drained'' down to
some threshold, the program resumes.
The header file <sgtty.h> declares structures and manifest constants
to control the sgtty interface. Of interest to users are the constants
that define baud rates for terminal ports; these are as follows.
B50 50 baud
B75 75 baud
B110 110 baud
B134 134 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
B19200 19,200 baud
B38400 38,400 baud
Terminal ioctl() Functions
Header file <sgtty.h> defines the following data structures used by
the various device drivers to convey terminal specific information. These
structures are used in conjunction with special terminal or device driver
symbolic constants as part of ioctl() requests.
The sgttyb structure contains information related to line discipline, such
as serial line speed, if appropriate, the ``erase'' and ``kill''
characters, and a series of flags which set the mode of the line.
/*
* Structure for TIOCSETP/TIOCGETP
*/
struct sgttyb {
char sg_ispeed;/* Input speed */
char sg_ospeed;/* Output speed */
char sg_erase; /* Character erase */
char sg_kill; /* Line kill character */
int sg_flags; /* Flags */
};
The following symbolic constants are used to access bit positions of member
sg_flags in data structure sgttyb:
CBREAK Each input character causes wakeup (i.e., forces a return from
a read() system call).
CRMOD Map the carriage return characters '\r' to the newline
character '\n'.
CRT Use CRT-style character erase.
ECHO Echo input characters.
EVENP Select even parity. If used in conjunction with ODDP, allow
either parity.
LCASE Lowercase mapping on input.
ODDP Select odd parity. If used in conjunction with EVENP, allow
either parity.
RAW Raw mode. Same as RAWIN plus RAWOUT.
RAWIN Input is treated as 8-bit characters and not interpreted.
RAWOUT Output is treated as 8-bit characters and not interpreted.
TANDEM Use X-ON/X-OFF flow control protocol to remote device.
XTABS Expand tabs to spaces.
Data structure tchars specifies additional special terminal characters such
as the ``interrupt'' and ``quit'' characters, the ``start'' and ``stop''
characters used for flow control, and the ``end-of-file'' character.
/*
* Structure for TIOCSETC/TIOCGETC
*/
struct tchars {
char t_intrc; /* Interrupt */
char t_quitc; /* Quit */
char t_startc; /* Start output */
char t_stopc; /* Stop output */
char t_eofc; /* End of file */
char t_brkc; /* Input delimiter */
};
The following symbolic constants are used to access various device
functions via ioctl() calls, as defined in header file <sgtty.h>.
Note that not all functions are appropriate for all classes of devices.
TIOCCBRK Clear a BREAK condition on a serial line (i.e., ``mark'' the
line). This request cancels a previously issued TIOCSBRK
request.
TIOCCDTR Clear modem control signal Data Terminal Ready (DTR) on a
serial line.
TIOCCHPCL Do not force a hangup on ``last close'' on a modem line. The
normal mode of operation for serial lines is to drop modem
signal Data Terminal Ready (DTR) when the last close()
operation is performed, thus requesting the attached modem to
drop the connection.
TIOCCRTS Clear the Request To Send (RTS) signal on a serial line. Modem
control signal RTS is often used for hardware flow control.
TIOCEXCL Set device access as exclusive use. This request requires the
process to have root privileges.
TIOCFLUSH Flush the input queue, discarding any pending input characters,
and wait for the output queue to ``drain''.
TIOCGETC Get current values of the special terminal characters, as
defined by data structure tchars.
TIOCGETF Get current console keyboard function key bindings. This
request is specific to the nkb console keyboard device driver.
See Lexicon article nkb for further details.
TIOCGETKBT Get current console keyboard key mapping table. This request
is specific to the nkb console keyboard device driver. See
Lexicon article nkb for further details.
TIOCGETP Get current terminal line settings, as defined by data
structure sgttyb.
TIOCGETTF Get current value of the terminal flags, as defined by field
t_flags in the TTY structure.
TIOCHPCL Set hangup on ``last close''. See TIOCCHPCL for further
details.
TIOCRMSR Get the current value of the Modem Status Register (MSR) for
the specified serial line. This request is device driver
specific and is currently supported only in the al device
driver. Symbolic constants MSRCTS, MSRDSR, MSRRI, and MSRRLSD
correspond to the Clear To Send, Data Set Ready, Ring Indicator
and Receive Line Status Detect (i.e. Carrier Detect) signals,
respectively, in the MSR.
TIOCNXCL Set this device or port as non-exclusive use. See TIOCEXCL for
further details.
TIOCQUERY Query the number of characters currently waiting in the input
queue.
TIOCSBRK Assert BREAK (i.e., ``space the line'') on the given serial
port. This is often used during login to signal a remote
system to ``hunt'' to the next baud rate in a sequence. See
TIOCCBRK for further details.
TIOCSDTR Assert modem control signal Data Terminal Ready (DTR) on a
serial line.
TIOCSETC Wait for output to ``drain'', then set the terminal control
characters for this device, as specified by data structure
tchars.
TIOCSETF Set console keyboard function key mapping. This request is
specific to the nkb console keyboard device driver. See
Lexicon article nkb for further details.
TIOCSETKBT Set console keyboard key mapping table. This request is
specific to the nkb console keyboard device driver. See
Lexicon article nkb for further details.
TIOCSETN Set terminal line settings, as defined by data structure
sgttyb. Do not flush the input queue prior to using the new
settings.
TIOCSETP Same as request TIOCSETN, but also flush the input queue.
TIOCSRTS Assert the Request To Send (RTS) signal on a serial line.
Modem control signal RTS is often used for hardware flow
control.
Examples
The following code fragment gets the current terminal settings and turns
off echo.
#include <sgtty.h>
static struct sgttyb new, orig;
. . .
/*
* Get the existing terminal parameters for the terminal
* device associated with file descriptor 0 (stdin),
* turn off echo, turn on CBREAK (break on every input character)
* and set the new parameters.
*/
ioctl(0, TIOCGETP, &orig);
new = orig;
new.sg_flags &= ~ECHO; /* Turn off echo */
new.sg_flags |= CBREAK; /* Turn on CBREAK mode */
ioctl(0, TIOCSETN, &new);
The following line uses the previously saved terminal mode to return the
terminal mode to its prior state:
ioctl(0, TIOCSETN, &orig);
See Also
device drivers,
gtty(),
ioctl(),
sgtty.h,
stty,
stty(),
terminal,
termio
