ldterm(7)ldterm(7)NAMEldterm - standard STREAMS terminal line discipline module
SYNOPSISDESCRIPTION
is a STREAMS module that supplies the line discipline for streams-based
terminal or pseudo-terminal device drivers. This module provides most
of the functions of the general terminal interface described in
termio(7). However, it does not perform the low-level device control
functions specified by the word defined by the POSIX structure or the
System V structure (defined in and respectively). Also, some opera‐
tions require the cooperation of the modules and drivers pushed below
the module in a tty or pty (slave) stream. This man page only covers
specific interface here and refers to the readers to termio(7) for the
detail terminal interface.
Internally, the module uses the Extended UNIX Code (EUC) character
encoding scheme. This encoding scheme enables the module to process
multibyte characters as well as simple 8-bit characters. It correctly
handles backspacing, word erasing, and tab expansion for multibyte EUC
characters.
The module provides standard terminal operation consistent with the
behavior specified by POSIX 1003.1 and System V Interface Definition
(SVID) Third Edition. It also provides compatibility with the behavior
of the BSD 4.3 line discipline. Notice that on other STREAMS systems,
the BSD 4.3 compatibility feature is usually provided by a separate
STREAMS module called Hence, applications on HP-UX need not push on top
of to get BSD 4.3 compatibility. In fact, the module is not provided
on the HP-UX system at all.
The module normally sits above either a STREAMS tty driver or a STREAMS
pty slave driver. The user issues an ioctl(2) system call to push onto
the stream once the STREAMS tty or STREAMS pty slave device is opened.
STREAMS Messages
The module processes various types of STREAMS messages. The line dis‐
cipline will act on any of the following message types. Any others
that the module receives, however, are passed onto the next module on
the stream.
Read-side Behavior
processes the following STREAMS messages on its input stream:
If is set, the read put routine flushes the read queue, discards
characters in the input message buffers, and discards any
partially buffered multibyte EUC characters. Then, it for‐
wards the message upstream.
The read put routine processes the message according to POSIX rules for
processing events, parity errors, and framing errors and sig‐
nal generation (see termio(7) for detail). If there is no
data in the message, the message is assumed to represent an
input event, which is represented by a framing error with a
character value of 0 (zero). If there is data in the mes‐
sage, the data value is an integer that indicates the occur‐
rence of an input event, or a character received with a par‐
ity or framing error. The low-order 8 bits of the data value
is the byte that was read. If the flag is set in the higher-
order bits of this integer, then a parity error was detected.
If the flag is set in the higher-order bits of this integer,
a framing error was detected.
After reading the data value, the read put routine discards
the message.
The read put routine processes the message according to the
POSIX 1003.1 specification, using multibyte processing for
backspacing, word erasing, and tab expansion as appropriate.
It generates echo characters and places them in the output
buffer to be sent downstream to the write queue. While pro‐
cessing incoming data, it scans for and characters and sends
messages downstream to the write queue, if needed.
If the total number of buffered input characters is more than
the high-water mark and is set, the read put routine sends an
message downstream. When the queue reduces its backlog below
the low water mark, it sends an message downstream.
If the number of buffered input characters reaches and the
flag is set, the read put routine discards new input charac‐
ters and sends a character (downstream. If is not set, it
flushes the input queue.
If the flag is set, the read put routine sends messages
upstream when the appropriate signal characters are encoun‐
tered. Then it discards the characters.
If a character matching is encountered, and the flag is set,
the read put routine sends an message upstream to flush all
write queues. The message is reflected by the stream head
and sent downstream through all the write queues.
If the character signifies the logical termination of input,
the read put routine sends the currently buffered characters
upstream to the stream head.
Logical termination of input depends on the state of the
flag. If is set, the module is in canonical input mode. In
that case, the read put routine logically terminates input at
the end of a line of input. Canonical line termination char‐
acters are and If is clear, the discipline module is in non‐
canonical or raw input mode. In that case, the read put rou‐
tine terminates input when at least bytes are present in the
input message buffer or the timer specified by expires (see
termio(7) for more details).
If the message acknowledges the POSIX
command, the read put routine copies the and speeds informa‐
tion, which is sent by the console driver downstream, from
the message into the internal POSIX structure. Then it
copies the internal POSIX structure into the message.
If the message acknowledges one of the POSIX set commands
(i.e. and the read put routine copies all of the data from
the message into the internal POSIX structure.
After this processing is done, the read put routine deter‐
mines if the I/O control command was originally a BSD 4.3 or
System V I/O control command that was converted to a POSIX
command by the write service routine. If so, it restores the
original data so that the message acknowledges the original
I/O control command. Then it forwards the message upstream.
This message was sent by the driver to make special requests to
The structure of messages is the same as that of messages.
The message block points to a message buffer containing an
data structure (defined in The member of this structure con‐
tains a command, just as it does in an message. The member
of the message block contains a pointer to an message block,
which contains data associated with the message.
The read put routine processes messages containing the fol‐
lowing commands:
Turn off input processing normally performed on upstream
messages. This is for the use of modules or drivers
that perform their own input processing such as pseudo-
terminal (see ptm(7) and pts(7)) in mode connected to a
program that performs the input processing.
Turn on input processing normally performed on upstream
messages. This message is sent when the driver want to
exit the mode.
Write-side Behavior
processes the following STREAMS messages on its output stream. Mes‐
sages not listed here are simply forwarded downstream.
The write put routine flushes the write queue and discards any
buffered output data. Then, it forwards the message down‐
stream.
The write service routine processes the data according
to the POSIX 1003.1 specification output flags. It sends the
processed characters downstream to the driver when the output
queue fills up and all of the data is processed.
The write put routine validates the format of the
message and checks for known commands. If the message format
is invalid, it turns the message into an message, and returns
the message upstream. If the I/O control command is not rec‐
ognized, it forwards the message downstream for processing by
other modules.
The write put routine determines if the command is one that
must be processed in the proper sequence relative to mes‐
sages. If so, it queues the message to the write queue for
later processing by the write service routine. Commands that
require processing in sequence are:
Otherwise, the module's write put routine processes the com‐
mand immediately. Detailed descriptions of the preceding
commands are provided in the subsection, below.
This message is sent by the stream head to notify downstream modules
when an
application has issued a read request and there is not enough
data queued at the stream head to satisfy the request. The
is sent downstream normally when is operating in non-canoni‐
cal input mode. If is positive, the write put routine starts
an input timer. When the timer expires, it sends all
buffered input upstream. Then, it forwards the message down‐
stream.
ioctl Commands
The module acts on two categories of commands:
· Primary terminal I/O control commands
· BSD 4.3 compatibility terminal I/O control commands
Detail descriptions on how to use these can be found on the termio(7)
man page. NOTE: the documented on termio(7) are currently not sup‐
ported on
Primary Terminal I/O Control Commands
The module acts on the following primary terminal I/O commands:
When the module receives any of these commands in an message, it for‐
wards them downstream. When it receives the message in the
read queue, it copies the POSIX information from the message
into the internal POSIX structure and forwards the message
upstream. If a mode change requires options at the stream
head to be changed, an message is sent upstream. If the flag
is turned on or off, the read mode at the stream head is
changed to message-nondiscard with read notification on or
byte-stream mode with read notification off respectively. If
the flag is turned on or off, the tostop mode at the stream
head is turned on or off respectively.
The module forwards the message downstream. When it receives the
message in the read queue, it copies the flags and speeds
from the message into the internal POSIX structure. Then, it
copies the entire structure into the message and forwards the
message upstream.
These commands set the old System V
information. The module converts the message to a POSIX mes‐
sage, then forwards the message with a corresponding POSIX
command (i.e. The original I/O control command and message
are stored for use on
This command get the old System V
information. The module converts the message to a POSIX mes‐
sage, then forwards the message with the command. The origi‐
nal I/O control command and message are stored to be used on
When it receives the matching message, the module processes
it as for a command, then converts the POSIX information into
the System V information and replies.
The module forwards this command downstream to be handled by the
driver so that the driver has a chance to drain the data
before sending an message upstream.
This command controls the behavior of input/output flow control.
If the argument is 0 and output is not already stopped, an
message is sent downstream. If the argument is 1 and the
output is stopped, an message is sent downstream. If the
argument is 2 and input is not already stopped, an message is
sent downstream. If the argument is 3 and input is stopped,
an message is sent downstream.
This command flush the input or/and output streams. If the argument is
0, an
message with a flag byte of is sent downstream. This message
will be reflected back upstream by the driver to flush the
entire input stream. If the argument is 1, an message with a
flag byte of is sent upstream. This message will be
reflected downstream by the stream head to flush the entire
output stream.
This command sets the window size variables.
The argument of this command takes a pointer to a structure.
The module does not use the window size variable, but main‐
tains it here for any needed replies to commands. The module
forwards the message downstream.
When the module receives this command, it returns the window size
variable that was set by the last command. The argument of
this command takes a pointer to a structure.
This command sets the character widths and screen widths for the EUC
character sets. The argument of this command takes a pointer
to an structure which contains the information for setting
the character widths and screen widths of the EUC character
sets. After processing the command, forwards this message
downstream to the next module.
This command returns the character widths and screen widths for the EUC
character sets. This command takes a pointer to an structure
via which the EUC character widths and screen widths informa‐
tion will be returned.
This command put
to the so called mode which enable to recognize the
HP15_SJIS, HP15_BIG5, HP15_CCDC, and HP15_GB character sets
and process them in such a way that they behave like EUC
characters. The argument for this command takes a pointer to
an integer value which specify on of the above-mentioned four
supported HP15 character sets. If the argument is set to
HP15_ASCII, then will switch back to normal ASCII processing.
is mutually exclusive with
This command returns the current HP15 character that has been set via
the
command. This command takes a pointer to an integer via
which the result is returned. If no previous has been
issued, then it will return HP15_ASCII.
BSD 4.3 Compatible Terminal I/O Commands
The module acts on the following I/O commands, which are compatible
with the BSD I/O environment:
Set `exclusive-use' mode. No further opens are permitted until the
file has been closed.
Turn off `exclusive-use' mode.
The module does nothing but reply to this command. In a BSD sys‐
tem, the command is used to set the current line discipline
type. It does not have much meaning in a STREAMS environ‐
ment, because line discipline modules are changed by popping
the current module from the stream and pushing a different
one onto the stream.
In a BSD system, this command is used to get the current line disci‐
pline
type. The command does not have much meaning in a STREAMS
environment. The module replies with a value of 2 for binary
compatibility, since supports job control.
This command flush the input or/and output streams similar to that of
the
command. The argument is a pointer to an variable. If its
value is zero, both the input and output streams are flushed
by sending the appropriate messages upstream and downstream.
Otherwise, the value of the is treated as the logical of the
and flags defined by If the flag is set, the input stream is
flushed. If the flag is set, the output stream is flushed.
Then, acknowledges the message with
This command takes a pointer to an integer and returns the number of
characters
buffered up in the output buffer.
This command sets the POSIX
flag to indicate that the terminal line should be discon‐
nected when the last file descriptor associated with that
line is closed. The module converts the command into a com‐
patible POSIX I/O control command by sending an message con‐
taining the command with current settings downstream.
The command restarts output. If the terminal was stopped, the
module sends an message downstream.
This command stops output. The
module sends an message downstream.
This command sets the break condition on a line.
The module sends an message containing a value of 1 as data
to the driver, then replies with
This command clears the break condition on a line.
The module sends an message containing a value of 0 (zero) as
data to the driver, then replies with
These commands set the
information, defined in The argument is a pointer to an
structure. The module converts the message to a POSIX mes‐
sage. Then, it forwards the POSIX message with a correspond‐
ing POSIX command The original I/O control command and mes‐
sage are stored for use on
This command
returns the information based on the interpretation of the
current content of the POSIX structure maintained in The
argument is a pointer to an structure via where the informa‐
tion is returned.
This command sets the
information, defined in The argument is a pointer to an
structure. The module converts the message to a POSIX mes‐
sage. Then, it forwards the POSIX message with a correspond‐
ing POSIX command The original I/O control command and mes‐
sage are stored for use on
This command
returns the information based on the interpretation of the
current content of the POSIX structure maintained in The
argument is a pointer to an structure via where the informa‐
tion is returned.
This command sets the
information defined in The module converts the message to a
POSIX message. Then, it forwards the POSIX message with a
corresponding POSIX command The original I/O control command
and message are stored for use on
The module returns the information based on the interpretation of
the current content of the POSIX structure maintained in
These commands set the BSD 4.3 flags information, defined in
For and the argument is a pointer to an whose value is a mask
containing flags to be set/clear. For the argument is a
pointer to an whose value is a new set of flags to be set.
The module converts the message to a POSIX then forwards the
POSIX message with a corresponding POSIX command It stores
the original I/O control command and message to be used on
The module returns the BSD 4.3 flags information based on the
interpretation of the current content of the POSIX structure
maintained in
This command takes an argument of a pointer to a character and pretends
that the character was typed on the terminal. The user must
either have the privilege or have read permission on the con‐
trolling terminal against which the ioctl is issued. See
privileges(5) for more information about privileged access on
systems that support fine-grained privileges.
This command takes an argument of a pointer to an integer and returns
the
number of immediately readable characters.
AUTHOR
was developed by HP and OSF.
SEE ALSOioctl(2), privileges(5), ptem(7), ptm(7), pts(7), streamio(7),
termio(7).
ldterm(7)
