'\"macro stdmacro
.if n .pH g7.ldterm @(#)ldterm	40.9 of 10/10/89
.\" Copyright 1989 AT&T
.nr X
.if \nX=0 .ds x} ldterm 7 "" "\&"
.if \nX=1 .ds x} ldterm 7 ""
.if \nX=2 .ds x} ldterm 7 "" "\&"
.if \nX=3 .ds x} ldterm "" "" "\&"
.TH \*(x}
.SH NAME
\f4ldterm\f1 \- standard \s-1STREAMS\s0 terminal line discipline module
.SH DESCRIPTION
\f4ldterm\fP is a \s-1STREAMS\s0 module that provides most of the
\f4termio\f1(7) terminal interface. 
This module does not perform the low-level
device control functions specified by flags in the \f4c_cflag\f1 word of the
\f4termio/termios\f1 structure or by the \f4IGNBRK, IGNPAR, PARMRK\fP, or \f4INPCK\fP 
flags in the \f4c_iflag\f1 word of the \f4termio/termios\f1 structure; 
those functions must be performed by the driver or by modules pushed below the 
\f4ldterm\fP module.
All other \f4termio/termios\f1 functions are performed by \f4ldterm\fP;
some of them, however, require the cooperation of the driver or
modules pushed below \f4ldterm\fP and may not be performed in some cases. 
These include the \f4IXOFF\fP flag in the \f4c_iflag\f1 word and the delays 
specified in the \f4c_oflag\f1 word.
.PP
\f4ldterm\fP also handles \s-1EUC\s0 and multi-byte characters.
.PP
The remainder of this section describes the processing of various
\s-1STREAMS\s+1 messages on the read- and write-side.
.SS "Read-side Behavior"
Various types of \s-1STREAMS\s0 messages are processed as follows:
.TP 0.5i
\f4M_BREAK\fP
When this message is received, either an
interrupt signal is generated or the message is treated as if it
were an \f4M_DATA\fP message containing a single \s-1ASCII NUL\s0 character, 
depending on the state of the \f4BRKINT\fP flag.
.TP 0.5i
\f4M_DATA\fP
This message is normally processed using the standard \f4termio\f1
input processing. 
If the \f4ICANON\fP flag is set, a single input record (``line'') is accumulated 
in an internal buffer and sent upstream when a line-terminating character
is received. 
If the \f4ICANON\fP flag is not set, other input processing is performed and the
processed data are passed upstream.
.IP
If output is to be stopped or started as a result of the arrival of
characters (usually \f4CNTRL-Q\fP and \f4CNTRL-S\fP), \f4M_STOP\fP and \f4M_START\fP messages are sent downstream. 
If the \f4IXOFF\fP flag is set and input is to be stopped or started as a result 
of flow-control considerations, \f4M_STOPI\fP and \f4M_STARTI\fP messages are 
sent downstream.
.IP
\f4M_DATA\fP messages are sent downstream, as necessary, to perform echoing.
.IP
If a signal is to be generated, an \f4M_FLUSH\fP message with a flag byte of
\f4FLUSHR\fP is placed on the read queue.
If the signal is also to flush output, an \f4M_FLUSH\fP message with a flag 
byte of \f4FLUSHW\fP is sent downstream.
.TP 0.5i
\f4M_CTL\fP
If the size of the data buffer associated with the message is the
size of \f4struct iocblk, ldterm\fP will perform functional negotiation to 
determine where the \f4termio\f1(7) processing is to be done. 
If the command field of the \f4iocblk\fP structure (\f4ioc_cmd\fP) is set to 
\f4MC_NO_CANON\fP, the input canonical processing normally performed on \f4M_DATA\fP
messages is disabled and those messages are passed upstream
unmodified; this is for the use of modules or drivers that perform their own
input processing, such as a pseudo-terminal in \f4TIOCREMOTE\fP mode connected 
to a program that performs this processing. 
If the command is \f4MC_DO_CANON\fP, all input processing is enabled.
If the command is \f4MC_PART_CANON\fP, then an \f4M_DATA\fP message containing a
\f4termios\f1 structure is expected to be attached to the original \f4M_CTL\fP
message. 
The \f4ldterm\fP module will examine the \f4iflag, oflag\fP, and \f4lflag\fP fields
of the
\f4termios\f1 structure and from then on will process only those flags which have
not been turned \s-1ON\s0.
If none of the above commands are found,
the message is ignored; in any case, the message is passed upstream.
.TP 0.5i
\f4M_FLUSH\fP
The read queue of the module is flushed of all its data messages
and all data in the record being accumulated are also flushed. 
The message is passed upstream.
.TP 0.5i
\f4M_IOCACK\fP
The data contained within the message, which is to be returned to the
process, are augmented if necessary, and the message is passed upstream.
.LP
All other messages are passed upstream unchanged.
.LE
.SS "Write-side Behavior"
Various types of \s-1STREAMS\s0 messages are processed as follows:
.TP 0.5i
\f4M_FLUSH\fP
The write queue of the module is flushed of all its data messages
and the message is passed downstream.
.TP 0.5i
\f4M_IOCTL\fP
The function of this \f4ioctl\f1 is performed and the message is passed downstream 
in most cases. 
The \f4TCFLSH\fP and \f4TCXONC ioctl\fPs can be performed entirely in the 
\f4ldterm\fP module, so the reply is sent upstream and the message is not passed 
downstream.
.TP 0.5i
\f4M_DATA\fP
If the \f4OPOST\fP flag is set, or both the \f4XCASE\fP and \f4ICANON\fP
flags are set, output processing is performed and the processed
message is passed downstream along with any \f4M_DELAY\fP messages generated. 
Otherwise, the message is passed downstream without change.
.LP
All other messages are passed downstream unchanged.
.SH IOCTLS
The following \f4ioctl\fPs are processed by the \f4ldterm\fP module. 
All others are passed downstream.
\f4EUC_WSET\fP and \f4EUC_WGET\fP are \f4I_STR ioctl\fP calls
whereas other \f4ioctl\fPs listed here are \f4TRANPARENT ioctl\fPs.
.TP 0.5i
\f4TCGETS/TCGETA\fP
The message is passed downstream; if an acknowledgment is seen, the
data provided by the driver and modules downstream are augmented and
the acknowledgement is passed upstream.
.TP 0.5i
\f4TCSETS/TCSETSW/TCSETSF/TCSETA/TCSETAW/TCSETAF\fP
The parameters that control the behavior of the \f4ldterm\fP module are changed.
If a mode change requires options at the stream head to be changed, an
\f4M_SETOPTS\fP message is sent upstream. 
If the \f4ICANON\fP flag is turned on or off, the read mode at the stream head
is changed to message-nondiscard or byte-stream mode, respectively.
If the \f4TOSTOP\fP flag is turned on or off, the tostop mode at the 
stream head is turned on or off, respectively.
.TP 0.5i
\f4TCFLSH\fP
If the argument is 0, an \f4M_FLUSH\fP message with a flag byte of \f4FLUSHR\fP
is sent downstream and placed on the read queue.
If the argument is 1, the write queue is flushed of all its data
messages and an \f4M_FLUSH\fP message with a flag byte of \f4FLUSHW\fP is sent 
upstream and downstream.
If the argument is 2, the write queue is flushed of all its data
messages and an \f4M_FLUSH\fP message with a flag byte of \f4FLUSHRW\fP is sent 
downstream and placed on the read queue.
.TP 0.5i
\f4TCXONC\fP
If the argument is 0 and output is not already stopped, an \f4M_STOP\fP
message is sent downstream.
If the argument is 1 and output is stopped, an \f4M_START\fP message is sent 
downstream.
If the argument is 2 and input is not already stopped, an \f4M_STOPI\fP
message is sent downstream.
If the argument is 3 and input is stopped, an \f4M_STARTI\fP message 
is sent downstream.
.TP 0.5i
\f4TCSBRK\fP
The message is passed downstream, so the driver has a chance to
drain the data and then send and an \f4M_IOCACK\fP message upstream.
.TP 0.5i
\f4EUC_WSET\fP
This call takes a pointer to an \f4eucioc\fP structure, and uses it to set the
\s-1EUC\s0 line discipline's local definition for the code set widths to be used
for subsequent operations.
Within the stream, the line discipline may optionally notify other modules of this
setting via \f4M_CTL\fP messages.
.TP 0.5i
\f4EUC_WGET\fP
This call takes a pointer to an \f4eucioc\fP structure, and returns in it the
\s-1EUC\s0 code set widths currently in use by the \s-1EUC\s0 line discipline.
.SH SEE ALSO
\f4termios\fP(2), \f4console\fP(7), \f4ports\fP(7), \f4termio\fP(7).
.br
\f2Programmer's Guide: \s-1STREAMS\s0\f1.
