TTY(K) UNIX System V TTY(K)
Name
tty: ttclose, ttin, ttinit, ttiwake, ttopen, ttout, ttowake,
ttread, ttrdchk, ttrstrt, ttselect, tttimeo, ttwrite,
ttxput, ttyflush, ttywait - tty driver routines
Syntax
#include "sys/types.h"
#include "sys/tty.h"
int
ttclose(tp)
struct tty *tp;
int
ttin(tp, code)
struct tty *tp;
int code;
int
ttinit(tp)
struct tty *tp;
int
ttioctl(tp, cmd, arg, mode)
struct tty *tp;
int cmd, arg, mode;
int
ttiwake(tp)
struct tty *tp;
int
ttopen(tp)
struct tty *tp;
int
ttout(tp)
struct tty *tp;
int
ttowake(tp)
struct tty *tp;
int
ttread(tp)
struct tty *tp;
int
ttrdchk(tp)
struct tty *tp;
int
ttrstrt(tp)
struct tty *tp;
int
ttselect(tp, rw)
struct tty *tp;
int rw;
int
tttimeo(tp)
struct tty *tp;
int
ttwrite(tp)
struct tty *tp;
int
ttxput(tp, ucp, ncode)
struct tty *tp;
int ncode;
union {
unsigned short ch;
struct cblock *ptr;
} ucp;
int
ttyflush(tp, rdwrt)
struct tty *tp;
int rdwrt;
int
ttywait(tp)
struct tty *tp;
Description
The routines are:
ttclose called by the line discipline zero l_close
routine to remove access to a tty device from
the process that called it. ttclose disables
ISOPEN from the t_state member of the tty
structure, calls ttioctl with the LDCLOSE
argument, and disables XCLUDE from the
t_lflag member of the tty structure.
ttin called by the line discipline zero l_input
routine to get characters from a TTY device.
ttin is called in a driver's interrupt
routine to process and move characters from
t_rbuf to the raw character queue, t_rawq.
ttin processes the termio(M) c_cc values of
VINTR, VQUIT, VSUSP, VSWTCH, VEOL, VERASE,
VKILL, and VEOF. In addition, ttin checks
that ICANON is set when processing the c_cc
VMIN and VTIME values. ttin performs input
escape mapping for internationalization
character processing. If the code argument
to ttin is L_BREAK, ttin sends the SIGINT
signal to all associated processes. ttin
then calls ttyflush to release both read and
write buffers, and returns if no characters
are found in t_rbuf. If either ECHO is set or
after processing international character
mapping, ttin calls the driver's xxproc
routine with T_OUTPUT set. xxproc can also
be called with T_SWTCH set if VSWTCH is
enabled and if NOFLSH is disabled. ttin
calls these other tty routines: ttyflush,
ttxput, tttimeo, and ttiwake.
ttinit initializes the tty structure for line
discipline 0. The following members of the
tty structure are initialized:
+ t_line - line discipline index is set to
0
+ t_iflag - terminal input control is set
to 0
+ t_oflag - terminal output control is set
to 0
+ t_lflag - line discipline terminal
control is set to 0
+ t_cflag - terminal hardware control is
set to these values: 1200 baud (SSPEED
variable), 8 bits (CS8 variable), enable
receiver (CREAD variable), hang up on
last close (HUPCL variable)
ttioctl used to allocate, deallocate, or move the
contents of terminal buffers. Called through
the l_ioctl function of the line switch
table. The cmd argument to ttioctl has the
following values:
+ LDOPEN - allocate a receive buffer,
initialize several t_rbuf members
(c_ptr, c_count, and c_size), and call
the driver's xxproc routine with T_INPUT
as the argument.
+ LDCLOSE - call the driver's xxproc
routine with the T_RESUME argument; call
ttywait to wait for data to clear the
UART; and call ttyflush to empty the
t_canq and t_rawq buffers, as well as
the contents of t_rbuf.
+ LDCHG - move contents of the raw queue,
t_rawq, to the canonical queue, t_canq.
LDCHG only works if ICANON is enabled.
ttiwake called from an interrupt routine to wake up
any processes that are asleep waiting for
characters to appear in the raw input queue,
t_rawq. ttiwake only works when IASLP is set
in the t_state field of the tty structure.
ttiwake disables IASLP.
ttowake called from an interrupt routine to wake up
any processes that are asleep waiting for
characters to appear in the output queue,
t_outq. ttowake only works when OASLP is set
in the t_state field of the tty structure.
ttowake disables OASLP.
ttread called from a driver's xxread routine
indirectly through the l_read line discipline
switch function. ttread conveys characters
processed by canon from the canonical queue,
t_canq, to the user process.
ttrdchk returns a non-zero value if there are
characters to be read. If carrier is present
(CARR_ON is enabled in t_state), ttrdchk
tests t_canq for characters. t_canq is the
queue for characters that have been processed
by the canon routine. If characters are
present, a 1 is returned. If characters are
not present, and canon is being used to
process characters from the terminal (ICANON
is set in t_lflag), then ttrdchk tests the
delimiter count to see if a delimiter has
been entered on the tty device. The
delimiter count is held in t_delct in the tty
structure. If a delimiter was received, 1 is
returned. If characters are not present, but
canon is not being used to process
characters, then the raw character queue,
t_rawq, is checked for characters. If
characters are waiting in the raw queue, 1 is
returned.
ttrstrt restart tty device output after a delay
timeout. ttrstrt performs only one task; it
calls the driver's xxproc routine with
arguments of tp and T_TIME. (tp is the
pointer to the tty structure passed through
from the argument to ttrstrt.)
ttselect ensure that a read or write can be performed
with no blocking. (If blocking occurs, the
process will be put to sleep until the I/O
can be satisfied.) Do not call sleep(K)
before calling ttselect, and do not call
ttselect from an interrupt routine. ttselect
has two modes determined by its rw argument.
These modes are SELREAD and SELWRITE.
tttimeo satisfy VTIME timing requirement for data
input. tttimeo does not execute if ICANON is
set, if VTIME or VMIN are not set, or if
there aren't any characters to process in the
raw queue, t_rawq. tttimeo calls timeout(K)
for the time specified in VTIME times the
number of ticks per second (Hz) divided by
10. While timeout is active, t_state is ORed
with RTO and TACT. When the timing finishes,
ttiwake is called to awaken any processes
that are sleeping on the raw input queue.
ttwrite called from the line discipline l_write
function call in a driver's xxwrite routine
to copy data from the user program into the
driver so that the data can be displayed on a
tty device. If there is no carrier, ttwrite
returns immediately. ttwrite requires user
context and therefore cannot be called from
an interrupt routine. If a paging fault
occurs while attempting to get the data from
user space, u.u_error is set to EFAULT. In
the course of the copy operation, u.u_base
and u.u_count are updated to reflect the
amount of data transferred. ttwrite calls
ttxput to write the data to the terminal.
Before data is fetched from user space, the
number of characters in the output queue,
t_outq, are checked to see if the count
exceeds the high water mark. The high water
mark is the point at which tty input is
suspended so that the characters coming in
don't overload the tty driver's ability to
process them and echo them to output. If the
count exceeds the high water mark, the
driver's xxproc routine is called with the
T_OUTPUT argument, and the process is put to
sleep until the tty driver can handle I/O
again. The process sleeps on the address of
t_outq at a priority of TTOPRI (above PZERO)
and can be awakened prematurely by a signal.
If a signal is sent to the sleeping process,
a longjmp(K) occurs, returning control to the
calling user process and putting EINTR in
u.u_error (errno in user space). If a write
occurs in the background, SIGTTOU is sent to
all processes in the current process group.
ttxput puts characters on the tty output queue
(t_outq), adds delays, expands tabs, and
handles carriage return and new line
characters. ttxput is called from both base
level to output characters to a tty device
and from interrupt level for echoing
characters read in from the tty device. If
the queue escape character, denoted as QESC,
is detected, it is put directly on the output
queue. The next character after QESC is
treated as a timer character if the octal
value is greater than 200. The timer
character is used in a timeout(K) call in
ttout. If the character after QESC is less
than 200, it is treated as an ordinary
character to be output.
If t_state contains EXTPROC, but t_lflag does
not contains XCASE, then no post processing
is required. Additionally in this state,
characters can be internationally mapped if
requested, and shipped to the output queue
for further processing. XCASE indicates that
special characters should be ``escaped'' by
being preceded with a backslash. Refer to
termio(M) for a list of characters that are
translated when XCASE is specified.
International character mapping is requested
if t_mstate is true. If XCASE processing is
required, then international character
mapping can also be requested, and processing
for QESC is available (QESC handling is not
available when no post processing is
required).
ttxput processes characters with octal values
greater than 200 as special characters and
performs delay processing if t_state does not
contain EXTPROC. If EXTPROC is set, than
delay processing is assumed to be handled by
an external process. Characters that may
require translation and also need to indicate
a delay are shown in the following table:
______________________________________
| Octal Value| Description |
|____________|________________________|
| 0201 | non-printing character|
| 0202 | backspace |
| 0203 | line feed |
| 0204 | tab |
| 0205 | vertical tab |
| 0206 | carriage return |
| 0207 | form feed |
|____________|________________________|
If delay handling is being provided by ttxput, then the
delay is calculated based on the value of t_oflag. The
ttout routine does the actual timed delay. ttxput outputs
the QESC character as well as the timing value ORed with
octal 0200.
ttyflush called to release character blocks to the free
list from the write buffer, t_outq, or from the
two read buffers, t_canq and t_rawq. The rdwrt
argument to ttyflush should be ANDed with either
FREAD to release read buffers, or with FWRITE to
release the write buffer. When the blocks in the
write buffer are released, the driver's xxproc
routine is called with the T_WFLUSH argument. If
t_state contains OASLP, any processes sleeping on
the address of t_outq are awakened and OASLP is
disabled, and if t_state contains TTIOW, then
TTIOW is disabled and all processes sleeping on
the address of t_oflag are awakened.
If the blocks in the read buffers are being
released, then the driver's xxproc routine is
called with the T_RFLUSH argument. If t_state
contains IASLP, IASLP is disabled and all
processes sleeping on t_rawq are awakened.
ttywait called to drain the contents of the universal
asynchronous receiver/transmitter (UART). ttywait
waits 11 bit times for the UART to empty of all
data. The baud rate is taken from t_cflag&CBAUD
and possible values are (in bits per second):
0.5, 50, 75, 110, 134, 150, 200, 300, 600, 1200,
1800, 2400, 4800, 9600, 19200, or 38400. If upon
entry to this routine, characters are in t_outq,
or t_state contains BUSY or TIMEOUT, then t_state
is ORed with TTIOW and the process is put to sleep
on the address of t_oflag at TTOPRI. TTOPRI has a
value above PZERO and therefore can be prematurely
awakened by a signal. Should a signal occur,
control returns to the user program and the EINTR
error code is placed in u.u_error and errno in the
user program.
Parameters
tp a pointer to the struct tty data
structure associated with the
device being accessed.
code used by ttin and can be set to
L_BREAK to cause all processes
associated with the terminal to be
sent a SIGINT signal, and to have
all character blocks on t_outq,
t_canq, and t_rawq queues be
released to the free list.
cmd, arg, or mode used by ttioctl to determine which
I/O control command is being
requested.
rw used by ttselect to determine
whether the driver is testing for
read or write access without
blocking. Possible values are
SELREAD or SELWRITE.
ucp, ncode used by ttxput. ucp describes a
union of a character or a pointer
to a block of characters. ncode is
a flag used to indicate which value
ucp contains; if ncode is zero (0),
ucp is a character; any other value
indicates that ucp is a pointer to
a cblock.
rdwrt used by ttyflush to indicate which
buffers to release to the free
list. AND with FREAD to indicate
that the cblocks in t_canq and
t_rawq should be released; AND with
FWRITE to indicate that the blocks
in the t_outq should be released.
Notes
All routines on this manual page can be used only with
character device drivers.
See Also
termio(M), canon(K), ttiocom(K)
(printed 7/6/89)