HPUX termios[7]
termio(7) termio(7)
NAME
termio, termios - general terminal interface
DESCRIPTION
All HP-UX asynchronous communications ports use the same general
interface, regardless of what hardware is involved. Network
connections such as rlogin (see rlogin(1) use the pseudo-terminal
interface (see pty(7).
This discussion centers around the common features of this interface.
Opening a Terminal File
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 special programs such as
getty (see getty(1M)) and become a user's standard input, standard
output, and standard error files.
If both the O_NDELAY and O_NONBLOCK flags (see open(2)) are clear, an
open blocks until the type of modem connection requested (see
modem(7)) is completed. If either the O_NDELAY or O_NONBLOCK flag is
set, an open succeeds and return immediately without waiting for the
requested modem connection to complete. The CLOCAL flag (see Control
Modes) can also affect open(2).
Process Groups
A terminal can have a foreground process group associated with it.
This foreground process group plays a special role in handling
signal-generating input characters.
Command interpreter processes can allocate the terminal to different
jobs (process groups) by placing related processes in a single process
group and associating this process group with the terminal. A
terminal's foreground process group can be set or examined by a
process, assuming that the permission requirements are met (see
tcsetpgrp(3C) or tcgetpgrp(3C)). The terminal interface aids in this
allocation by restricting access to the terminal by processes that are
not in the foreground process group.
A process group is considered orphaned when the parent of every member
of the process group is either itself a member of the process group or
is not a member of the group's session (see Sessions).
Sessions
A process that creates a session (see setsid(2) or setpgrp(2)) becomes
a session leader. Every process group belongs to exactly one session.
A process is considered to be a member of the session of which its
process group is a member. A newly created process joins the session
of its parent. A process can change its session membership (see
setpgid(2) or setpgrp2(2)). Usually a session comprises all the
processes (including children) created as a result of a single login.
Hewlett-Packard Company - 1 - HP-UX Release 9.0: August 1992
termio(7) termio(7)
The Controlling Terminal
A terminal can belong to a process as its controlling terminal. Each
process of a session that has a controlling terminal has the same
controlling terminal. A terminal can be the controlling terminal for
at most one session. The controlling terminal for a session is
allocated by the session leader. If a session leader has no
controlling terminal and opens a terminal device file that is not
already associated with a session without using the O_NOCTTY option
(see open(2), the terminal becomes the controlling terminal of the
session and the controlling terminal's foreground process group is set
to the process group of the session leader. While a controlling
terminal is associated with a session, the session leader is said to
be the controlling process of the controlling terminal.
The controlling terminal is inherited by a child process during a
fork() (see fork(2)). A process relinquishes its controlling terminal
if it creates a new session with setsid() or setpgrp() (see setsid(2)
and setpgrp(2)), or when all file descriptors associated with the
controlling terminal have been closed.
When the controlling process terminates, the controlling terminal is
disassociated from the current session, allowing it to be acquired by
a new session leader. A SIGHUP signal is sent to all processes in the
foreground process group of the controlling terminal. Subsequent
access to the terminal by other processes in the earlier session can
be denied (see Terminal Access Control) with attempts to access the
terminal treated as if a modem disconnect had been sensed.
Terminal Access Control
Read operations are allowed (see Input Processing and Reading Data)
from processes in the foreground process group of their controlling
terminal. If a process is not in the foreground process group of its
controlling terminal, the process and all member's of its process
group are considered to be in a background process group of this
controlling terminal. All attempts by a process in a background
process group to read from its controlling terminal will be denied.
If denied and the reading process is ignoring or blocking the SIGTTIN
signal, or the process (on systems that implement vfork separately
from fork) has made a call to vfork(2) but has not yet made a call to
exec(2), or the process group of the reading process is orphaned,
read() returns -1 with errno set to EIO and no signal is sent. In all
other cases where the read is denied, the process group of the reading
process will be sent a SIGTTIN signal. The default action of the
SIGTTIN signal is to stop the process to which it is sent.
If the process is in the foreground process group of its controlling
terminal, write operations are allowed (see Writing Data and Output
Processing). Attempts by a process in a background process group to
write to its controlling terminal are denied if TOSTOP (see Local
Modes) is set, the process is not ignoring and not blocking the
SIGTTOU signal, and the process (on systems that implement vfork
Hewlett-Packard Company - 2 - HP-UX Release 9.0: August 1992
termio(7) termio(7)
separately from fork) has not made a call to vfork(2) without making a
subsequent call to exec(2). If the write is denied and the background
process group is orphaned, the write() returns -1 with errno set to
EIO. If the write is denied and the background process group is not
orphaned, the SIGTTOU signal is sent to the process group of the
writing process. The default action of the SIGTTOU signal is to stop
the process to which it is sent.
Certain calls that set terminal parameters are treated in the same
fashion as write, except that TOSTOP is ignored; that is, the effect
is identical to that of terminal writes when TOSTOP is set.
Input Processing and Reading Data
A terminal device associated with a terminal device file can operate
in full-duplex mode, so that data can arrive, even while data output
is occurring. Each terminal device file has an input queue associated
with it into which incoming data is stored by the system before being
read by a process. The system imposes a limit, MAX_INPUT, on the
number of characters that can be stored in the input queue. This
limit is dependent on the particular implementation, but is at least
256. When the input limit is reached, all saved characters are
discarded without notice.
All input is processed either in canonical mode or non-canonical mode
(see Canonical Mode Input Processing and Non-Canonical Mode Input
Processing). Additionally, input characters are processed according
to the c_iflag (see Input Modes) and c_lflag (see Local Modes) fields.
For example, such processing can include echoing, which in general
means transmitting input characters immediately back to the terminal
when they are received from the terminal. This is useful for
terminals that operate in full-duplex mode.
The manner in which data is provided to a process reading from a
terminal device file depends on whether the terminal device file is in
canonical or non-canonical mode.
Another dependency is whether the O_NONBLOCK or O_NDELAY flag is set
by either open(2) or fcntl(2). If the O_NONBLOCK and O_NDELAY flags
are both clear, the read request is blocked until data is available or
a signal is received. If either the O_NONBLOCK or O_NDELAY flag is
set, the read request completes without blocking in one of three ways:
o If there is enough data available to satisfy the entire
request, read() completes successfully, having read all of the
data requested, and returns the number of characters read.
o If there is not enough data available to satisfy the entire
request, read() completes successfully, having read as much
data as possible, and returns the number of characters read.
Hewlett-Packard Company - 3 - HP-UX Release 9.0: August 1992
termio(7) termio(7)
o If there is no data available, read() returns -1, with errno
set to EAGAIN when the O_NONBLOCK flag is set. Otherwise,
(flag O_NONBLOCK is clear and O_NDELAY is set) read()
completes successfully, having read no data, and returns a
count of 0.
The availability of data depends upon whether the input processing
mode is canonical or non-canonical. The following sections, Canonical
Mode Input Processing and Non-Canonical Mode Input Processing,
describe each of these input processing modes.
Canonical Mode Input Processing (Erase and Kill Processing)
In canonical mode input processing, terminal input is processed in
units of lines, where a line is delimited by a new-line (NL)
character, an end-of-file (EOF) character, or an end-of-line character
(EOL). See Special Characters for more information on NL, EOF, and
EOL. This means that a read request does not return until an entire
line has been typed or a signal has been received. 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 can be requested in a read, even
one, without losing information.
MAX_CANON is the limit on the number of characters in a line. This
limit varies with each particular implementation, but is at least 256.
When the MAX_CANON limit is reached, all characters in the current
undelimited line are discarded without notice.
Erase and kill processing occur when either of two special characters,
the ERASE and KILL characters (see Special Characters), is received.
This processing affects data in the input queue that has not yet been
delimited by a NL, EOF, or EOL character. This undelimited data makes
up the current line. The ERASE character deletes the last character
in the current line, if one exists. The KILL character deletes all
data in the current line, if any, and optionally outputs a new-line
(NL) character. Both of these characters operate on a key-stroke
basis, independent of any backspacing or tabbing that may have
preceded them. ERASE and KILL characters have no effect if the the
current line is empty. ERASE and KILL characters are not placed in
the input queue.
Non-Canonical Mode Input Processing (MIN/TIME Interaction)
In non-canonical mode input processing, input characters are not
assembled into lines, and erase and kill processing does not occur.
The values of the MIN and TIME members of the c_cc array (see termios
Structure) are used to determine how to process the characters
received. MIN represents the minimum number of characters that should
be received before read() successfully returns. TIME is a timer of
Hewlett-Packard Company - 4 - HP-UX Release 9.0: August 1992
termio(7) termio(7)
0.10 second granularity that is used to timeout bursty and short term
data transmissions. The four possible cases for MIN and TIME and
their interactions are described below.
Case A: MIN > 0, TIME > 0
In this case, TIME serves as an inter-character timer and is activated
after the first character is received. Since it is an inter-character
timer, it is reset after each character is received. The interaction
between MIN and TIME is as follows:
o As soon as one character is received, the inter-character
timer is started.
o If MIN characters are received before the inter-character
timer expires (remember that the timer is reset upon receipt
of each character), the read is satisfied. If the timer
expires before MIN characters are received, the characters
received to that point are returned to the user.
o Note that if TIME expires, at least one character will be
returned because the timer would not have been enabled unless
a character was received. In this case ( MIN > 0, TIME > 0 )
the read blocks until the MIN and TIME mechanisms are
activated by the receipt of the first character, or a signal
is received.
Case B: MIN > 0, TIME = 0
In this case, since the value of TIME is zero, the timer plays no role
and only MIN is significant. A pending read is not satisfied until
MIN characters are received after any previous read completes (that
is, the pending read blocks until MIN characters are received), or a
signal is received. A program that uses this case to handle record-
based terminal I/O can block indefinitely in the read operation.
Case C: MIN = 0, TIME > 0
In this case, since the value of MIN is zero, TIME no longer
represents an inter-character timer. It now serves as a read timer
that is activated as soon as the read() function is processed. A read
is satisfied as soon as a single character is received or the read
timer expires. If the timer expires, no character is returned. If
the timer does not expire, the only way the read can be satisfied is
by a character being received. A read cannot block indefinitely
waiting for a character because if no character is received within
TIME x 0.10 seconds after the read is initiated, read() returns a
value of zero, having read no data.
Case D: MIN = 0, TIME = 0
Hewlett-Packard Company - 5 - HP-UX Release 9.0: August 1992
termio(7) termio(7)
The number of characters requested or the number of characters
currently available, whichever is less, is returned without waiting
for more characters to be input. If no characters are available,
read() returns a value of zero, having read no data.
Some points to note about MIN and TIME:
1. In the above explanations, the interactions of MIN and TIME
are not symmetric. For example, when MIN > 0 and TIME = 0,
TIME has no effect. However, in the opposite case where MIN
= 0 and TIME > 0, both MIN and TIME play a role in that MIN
is satisfied with the receipt of a single character.
2. Also note that in case A ( MIN > 0, TIME > 0 ), TIME
represents an inter-character timer while in case C ( MIN =
0, TIME > 0 ), TIME represents a read timer.
These two points highlight the dual purpose of the MIN/TIME feature.
Cases A and B (where MIN > 0 ) exist to handle burst mode activity
(such as file transfer programs) where a program would like to process
at least MIN characters at a time. In case A, the inter-character
timer is activated by a user as a safety measure while in case B it is
turned off.
Cases C and D exist to handle single character timed transfers. These
cases are readily adaptable to screen-based applications that need to
know if a character is present in the input queue before refreshing
the screen. In case C the read is timed, while in case D it is not.
Another important note is that MIN is always just a minimum. It does
not denote a record length. For example, if a program initiates a
read of 20 characters when MIN is 10 and 25 characters are present, 20
characters will be returned to the user. Had the program requested
all characters, all 25 characters would be returned to the user.
Furthermore, if TIME is greater than zero and MIN is greater than
MAX_INPUT, the read will never terminate as a result of MIN characters
being received because all the saved characters are discarded without
notice when MAX_INPUT is exceeded. If TIME is zero and MIN is greater
than MAX_INPUT, the read will never terminate unless a signal is
received.
Special Characters
Certain characters have special functions on input, output, or both.
Unless specifically denied, each special character can be changed or
disabled. To disable a character, set its value to _POSIX_VDISABLE
(see unistd(5)). These special functions and their default character
values are:
INTR (Rubout or ASCII DEL) special character on input and
is recognized if ISIG (see Local Modes) is enabled.
Hewlett-Packard Company - 6 - HP-UX Release 9.0: August 1992
termio(7) termio(7)
Generates a SIGINT signal which is sent to all
processes in the foreground process group for which
the terminal is the controlling terminal. Normally,
each such process is forced to terminate, but
arrangements can be made to either ignore or hold
the signal, or to receive a trap to an agreed-upon
location; see signal(2) and signal(5). If ISIG is
set, the INTR character is discarded when processed.
If ISIG is clear, the INTR character is processed as
a normal data character, and no signal is sent.
QUIT (Ctrl-| or ASCII FS) special character on input.
Recognized if ISIG (see Local Modes) is set. The
treatment of this character is identical to that of
the INTR character except that a SIGQUIT signal is
generated and the processes that receive this signal
are not only terminated, but a core image file
(called core) is created in the current working
directory if the implementation supports core files.
SWTCH (ASCII NUL) special character on input and is only
used by the shell layers facility shl(1). The shell
layers facility is not part of the general terminal
interface. No special functions are performed by
the general terminal interface when SWTCH characters
are encountered.
ERASE (#) special character on input and is recognized if
ICANON (see Local Modes) is enabled. Erases the
preceding character. Does not erase beyond the
start of a line, as delimited by a NL, EOF, or EOL
character. If ICANON is enabled, the ERASE
character is discarded when processed. If ICANON is
not enabled, the ERASE character is treated as a
normal data character.
KILL (@) special character on input and is recognized if
ICANON is enabled. KILL deletes the entire line, as
delimited by a NL, EOF, or EOL character. If ICANON
is enabled, the KILL character is discarded when
processed. If ICANON is not enabled, the KILL
character is treated as a normal data character.
EOF (Control-D or ASCII EOT) special character on input
and is recognized if ICANON is enabled. EOF can be
used to generate an end-of-file from a terminal.
When received, all the characters waiting to be read
are immediately passed to the program without
waiting for a new-line, and the EOF is discarded.
Thus, if there are no characters waiting, (that is,
the EOF occurred at the beginning of a line) a
Hewlett-Packard Company - 7 - HP-UX Release 9.0: August 1992
termio(7) termio(7)
character count of zero is returned from read(),
representing an end-of-file indication. If ICANON
is enabled, the EOF character is discarded when
processed. If ICANON is not enabled, the EOF
character is treated as a normal data character.
NL (ASCII LF) special character on input and is
recognized if ICANON flag is enabled. It is the
line delimiter (\n). If ICANON is not enabled, the
NL character is treated as a normal data character.
EOL (ASCII NUL) special character on input and is
recognized if ICANON is enabled. EOL is an
additional line delimiter similar to NL. It is not
normally used. If ICANON is not enabled, the EOL
character is treated as a normal data character.
SUSP (disabled) special character recognized on input.
If ISIG is enabled, receipt of the SUSP character
causes a SIGTSTP signal to be sent to all processes
in the foreground process group for which the
terminal is the controlling terminal, and the SUSP
character is discarded when processed. If ISIG is
not enabled, the SUSP character is treated as a
normal data character. Command interpreter
processes typically set SUSP to Control-Z.
STOP (Control-S or ASCII DC3) special character on both
input and output. If IXON (output control) is
enabled, processing of the STOP character
temporarily suspends output to the terminal device.
This is useful with CRT terminals to prevent output
from disappearing before it can be read. While
output is suspended and IXON is enabled, STOP
characters are ignored and not read. If IXON is
enabled, the STOP character is discarded when
processed. If IXON is not enabled, the STOP
character is treated as a normal data character. If
IXOFF (input control) is enabled, the system sends a
STOP character to the terminal device when the
number of unread characters in the input queue is
approaching a system specified limit. This is an
attempt to prevent this buffer from overflowing by
telling the terminal device to stop sending data.
START (Control-Q or ASCII DC1) special character on both
input and output. If IXON (output control) is
enabled, processing of the START character resumes
output that has been suspended. While output is not
suspended and IXON is enabled, START characters are
ignored and not read. If IXON is enabled, the START
Hewlett-Packard Company - 8 - HP-UX Release 9.0: August 1992
termio(7) termio(7)
character is discarded when processed. If IXON is
not enabled, the START character is treated as a
normal data character. If IXOFF (input control) is
enabled, the system sends a START character to the
terminal device when the input queue has drained to
a certain system-defined level. This occurs when
the input queue is no longer in danger of possibly
overflowing.
CR (ASCII CR) special character on input is recognized
if ICANON is enabled. When ICANON and ICRNL are
enabled and IGNCR is not enabled, this character is
translated into a NL, and has the same affect as the
NL character. If ICANON and IGNCR are enabled, the
CR character is ignored. If ICANON is enabled and
both ICRNL and IGNCR are not enabled, the STOP
character is treated as a normal data character.
The NL, CR, START, and STOP characters cannot be changed or
disabled. The character values for INTR, QUIT, ERASE, KILL, EOF,
SWTCH, SUSP, and EOL can be changed or disabled to suit individual
tastes. If ICANON is set (see Local Modes), the ERASE, KILL, and
EOF characters can be escaped by a preceding \ character, in which
case no special function is performed.
If two or more special characters have the same value, the function
performed when the character is processed is undefined.
Modem Disconnect
If a modem disconnect is detected by the terminal interface for a
controlling terminal, and if CLOCAL is clear in the c_cflag field for
the terminal (see Control Modes), the SIGHUP signal is sent to the
controlling process of the controlling terminal. Unless other
arrangements have been made, this causes the controlling process to
terminate. Any subsequent read from the terminal device returns with
an end-of-file indication until the device is closed. Thus, processes
that read a terminal file and test for end-of-file can terminate
appropriately after a disconnect. Any subsequent write() to the
terminal device returns -1, with errno set to EIO, until the device is
closed.
Closing a Terminal Device File
The last process to close a terminal device file causes any output not
already sent to the device to be sent to the device even if output was
suspended. This last close always blocks (even if non-blocking I/O
has been specified) until all output has been sent to the terminal
device. Any input that has been received but not read is discarded.
Writing Data and Output Processing
When characters are written, they are placed on the output queue.
Characters on the output queue are transmitted to the terminal as soon
Hewlett-Packard Company - 9 - HP-UX Release 9.0: August 1992
termio(7) termio(7)
as previously-written characters are sent. These characters are
processed according to the c_oflag field (see Output Modes). Input
characters are echoed by putting them in the output queue as they
arrive. If a process produces characters for output more rapidly than
they can be sent, the process is suspended when its output queue
exceeds some limit. When the queue has drained down to some
threshold, the process is resumed.
termios Structure
Routines that need to control certain terminal I/O characteristics can
do so by using the termios structure as defined in the header file
<termios.h>. The structure is defined as follows:
#define NCCS 16
struct termios {
tcflag_t c_iflag; /* input modes */
tcflag_t c_oflag; /* output modes */
tcflag_t c_cflag; /* control modes */
tcflag_t c_lflag; /* local modes */
tcflag_t c_reserved; /* reserved for future use */
cc_t c_cc[NCCS]; /* control chars */
};
The special characters are defined by the array c_cc. The relative
positions and initial values for each special character function are
as follows:
lp-1 lp-1 lp-1.
EOF VEOF Control-D
EOL VEOL NUL
ERASE VERASE #
INTR VINTR DEL
KILL VKILL @
MIN VMIN NUL
QUIT VQUIT Control-|
START VSTART Control-Q
STOP VSTOP Control-S
SUSP VSUSP disabled
SWTCH VSWTCH NUL
TIME VTIME Control-D
termio Structure
The termio structure has been superseded by the termios structure and
is provided for backward compatibility with prior applications (see
termio Caveats). The structure is defined in the header file
<termio.h> and is defined as follows:
#define NCC 8
struct termio {
unsigned short c_iflag; /* input modes */
unsigned short c_oflag; /* output modes */
Hewlett-Packard Company - 10 - HP-UX Release 9.0: August 1992
termio(7) termio(7)
unsigned short c_cflag; /* control modes */
unsigned short c_lflag; /* local modes */
char c_line; /* line discipline */
unsigned char c_cc[NCC]; /* control chars */
};
Modes
The next four sections describe the specific terminal characteristics
that can be set using the termios and termio structures (see termio
Caveats). Any bits in the modes fields that are not explicitly
defined below are ignored. However, they should always be clear to
prevent future compatibility problems.
Input Modes
The c_iflag field describes the basic terminal input control:
IGNBRK Ignore break condition.
BRKINT Signal interrupt on break.
IGNPAR Ignore characters with parity errors.
PARMRK Mark parity errors.
INPCK Enable input parity check.
ISTRIP Strip character.
INLCR Map NL to CR on input.
IGNCR Ignore CR.
ICRNL Map CR to NL on input.
IUCLC Map uppercase to lowercase on input.
IXON Enable start/stop output control.
IXANY Enable any character to restart output.
IXOFF Enable start/stop input control.
A break condition is defined as a sequence of zero-value bits that
continues for more than the time to send one character. For example, a
character framing or parity error with data all zeros is interpreted
as a single break condition.
If IGNBRK is set, the break condition is ignored. Therefore the break
condition cannot be read by any process. If IGNBRK is clear and
BRKINT is set, the break condition flushes both the input and output
queues and, if the terminal is the controlling terminal of a
foreground process group, the break condition generates a single
SIGINT signal to that foreground process group. If neither IGNBRK nor
BRKINT is set, a break condition is read as a single \0 character, or
if PARMRK is set, as the three-character sequence \377, \0, \0.
If IGNPAR is set, characters with other framing and parity errors
(other than break) are ignored.
If PARMRK is set, and IGNPAR is clear, a character with a framing or
parity error (other than break) is read as the three-character
sequence: \377, \0, X, where X is the data of the character received
in error. To avoid ambiguity in this case, if ISTRIP is clear, a
Hewlett-Packard Company - 11 - HP-UX Release 9.0: August 1992
termio(7) termio(7)
valid character of \377 is read as \377, \377. If both PARMRK and
IGNPAR are clear, a framing or parity error (other than break) is read
as the character \0.
If INPCK is set, input parity checking is enabled. If INPCK is clear,
input parity checking is disabled. Whether input parity checking is
enabled or disabled is independent of whether parity detection is
enabled or disabled (see Control Modes). If PARENB is set (see
Control Modes) and INPCK is clear, parity generation is enabled but
input parity checking is disabled; the hardware to which the terminal
is connected will recognize the parity bit, but the terminal special
file will not check whether this bit is set correctly or not.
The following table shows the interrelationship between the flags
IGNBRK, BRKINT, IGNPAR, and PARMRK. The column marked Input gives
various types of input characters received, indicated as follows:
0 NUL character (\0)
C Character other than NUL
P Parity error detected
F Framing error detected
Items enclosed in brackets indicate one or more of the conditions are
true.
If the INPCK flag is clear, characters received with parity errors are
not processed according to this table, but instead, as if no parity
error had occurred. Under the flag columns, Set indicates the flag is
set, Clear indicates the flag is not set, and X indicates the flag may
be set or clear. The column labeled Read shows the results that will
be passed to the application code. A - indicates that no character or
condition is passed to the application code. The value SIGINT
indicates that no character is returned, but that the SIGINT signal is
sent to the foreground process group of the controlling terminal.
center; c c c c c c.
Input IGNBRK BRKINT IGNPAR PARMRK Read _
0[PF] Set X X X -
0[PF] Clear Set X X SIGINT
0[PF] Clear Clear X Set '\377','\0','\0'
0[PF] Clear Clear X Clear '\0'
C[PF] X X Set X -
C[PF] X X Clear Set '\377','\0',C
C[PF] X X Clear Clear '\0'
If ISTRIP is set, valid input characters are first stripped to 7-bits,
otherwise all 8-bits are processed.
If INLCR is set, a received NL character is translated into a CR
character. If IGNCR is set, a received CR character is ignored (not
read). If IGNCR is clear and ICRNL is set, a received CR character is
Hewlett-Packard Company - 12 - HP-UX Release 9.0: August 1992
termio(7) termio(7)
translated into a NL character.
If IUCLC and IEXTEN are set, a received uppercase alphabetic character
is translated into the corresponding lowercase character.
If IXON is set, start/stop output control is enabled. A received STOP
character suspends output and a received START character restarts
output. If IXANY, IXON, and IEXTEN are all set, any input character
without a framing or parity error restarts output that has been
suspended. When these three flags are set, output suspended, and an
input character received with a framing or parity error, output
resumes if processing it results in data being read. When IXON is
set, START and STOP characters are not read, but merely perform flow
control functions. When IXON is clear, the START and STOP characters
are read.
If IXOFF is set, start/stop input control is enabled. The system
transmits a STOP character when the number of characters in the input
queue exceeds a system defined value (high water mark). This is
intended to cause the terminal device to stop transmitting data in
order to prevent the number of characters in the input queue from
exceeding MAX_INPUT. When enough characters have been read from the
input queue that the number of characters remaining is less than
another system defined value (low water mark), the system transmits a
START character which is intended to cause the terminal device to
resume transmitting data (without risk of overflowing the input
queue). In order to avoid potential deadlock, IXOFF is ignored in
canonical mode whenever there is no line delimiter in the input
buffer. In this case, the STOP character is not sent at the high
water mark, but will be transmitted later if a delimiter is received.
If all complete lines are read from the input queue leaving only a
partial line with no line delimiter, the START character is sent, even
if the number of characters is still greater than the low water mark.
When ICANON is set and the input stream contains more characters
between line delimiters than the high water mark allows, there is no
guarantee that IXOFF can prevent buffer overflow and data loss,
because the STOP character may not be sent in time, if at all.
The initial input control value is all bits clear.
Output Modes
The c_oflag field specifies the system treatment of output:
OPOST Postprocess output.
OLCUC Map lowercase to uppercase on output.
ONLCR Map NL to CR-NL on output.
OCRNL Map CR to NL on output.
ONOCR No CR output at column 0.
ONLRET NL performs CR function.
OFILL Use fill characters for delay.
Hewlett-Packard Company - 13 - HP-UX Release 9.0: August 1992
termio(7) termio(7)
OFDEL Fill is DEL, else NUL.
NLDLY Select new-line delays:
NL0 No delay
NL1 Delay type 1
CRDLY Select carriage-return delays:
CR0 No delay
CR1 Delay type 1
CR2 Delay type 2
CR3 Delay type 3
TABDLY Select horizontal-tab delays:
TAB0 No delay
TAB1 Delay type 1
TAB2 Delay type 2
TAB3 Expand tabs to spaces.
BSDLY Select backspace delays:
BS0 No delay
BS1 Delay type 1
VTDLY Select vertical-tab delays:
VT0 No delay
VT1 Delay type 1
FFDLY Select form-feed delays:
FF0 No delay
FF1 Delay type 1
If OPOST is set, output characters are post-processed as indicated by
the remaining flags; otherwise characters are transmitted without
change.
If OLCUC is set, a lowercase alphabetic character is transmitted as
the corresponding uppercase character. This function is often used in
conjunction with IUCLC.
If ONLCR is set, the NL character is transmitted as the CR-NL
character pair. If OCRNL is set, the CR character is transmitted as
the NL character. If ONOCR is set, no CR character is transmitted
when at column 0 (first position). If ONLRET is set, the NL character
is assumed to do the carriage-return function; the column pointer will
be set to 0, and the delays specified for CR will be used. If ONLRET
is clear, the NL character is assumed to perform only the line-feed
function; the delays specified for NL are used and the column pointer
remains unchanged. For all of these cases, the column pointer is
always set to 0 if the CR character is actually transmitted.
The delay bits specify how long transmission stops to allow for
mechanical or other movement when certain characters are sent to the
terminal. The values of NL0, CR0, TAB0, BS0, VT0, and FF0 indicate no
delay. If OFILL is set, fill characters are transmitted for delay
instead of a timed delay. This is useful for high baud rate
terminals, that need only a minimal delay. If OFDEL is set, the fill
character is DEL; otherwise NUL.
Hewlett-Packard Company - 14 - HP-UX Release 9.0: August 1992
termio(7) termio(7)
If a form-feed or vertical-tab delay is specified, it lasts for about
2 seconds.
New-line delay lasts about 0.10 seconds. If ONLRET is set, carriage-
return delays are used instead of the new-line delays. If OFILL is
set, two fill characters are transmitted.
Carriage-return delay type 1 depends on the current column position;
type 2 is about 0.10 seconds; type 3 about 0.15 seconds. If OFILL is
set, delay type 1 transmits two fill characters; type 2, four fill
characters.
Horizontal-tab delay type 1 is depends on the current column position.
Type 2 is about 0.10 seconds; type 3 specifies that tabs are to be
expanded into spaces. If OFILL is set, two fill characters are
transmitted for any delay.
Backspace delay lasts about 0.05 seconds. If OFILL is set, one fill
character is transmitted.
The actual delays depend on line speed and system load.
The initial output control value is all bits clear.
Control Modes
The c_cflag field describes the hardware control of the terminal:
center tab(;); lBp-1 lB lBp-1 lB lp-1 l lp-1 l. CBAUD;Baud
rate:;CSIZE;Character size: B0;Hang up;CS5;5 bits B50;50
baud;CS6;6 bits B75;75 baud;CS7;7 bits B110;110 baud;CS8;8 bits
B134;134.5 baud; B150;150 baud;CSTOPB;Send two stop bits, else
one. B200;200 baud;CREAD;Enable receiver. B300;300
baud;PARENB;Parity enable. B600;600 baud;PARODD;Odd parity, else
even. B900;900 baud;HUPCL;Hang up on last close. B1200;1200
baud;CLOCAL;Local line, else dial-up. B1800;1800
baud;LOBLK;Reserved for use by shl(1). B2400;2400 baud;
B3600;3600 baud; B4800;4800 baud; B7200;7200 baud; B9600;9600
baud; B19200;19200 baud; B38400;38400 baud; EXTA;External A;
EXTB;External B;
The CBAUD bits specify the baud rate. The zero baud rate, B0, is used
to hang up the connection. If B0 is specified, the modem control
lines (see modem(7)) cease to be asserted. Normally, this disconnects
the line. For any particular hardware, impossible speed changes are
ignored. CBAUD is provided for use with the termio structure. When
the termios structure is used, several routines are available for
setting and getting the input and output baud rates (see termios
Structure Related Functions).
Hewlett-Packard Company - 15 - HP-UX Release 9.0: August 1992
termio(7) termio(7)
The CSIZE bits specify the character size in bits for both
transmission and reception. This size does not include the parity
bit, if any. If CSTOPB is set, two stop bits are used; otherwise one
stop bit. For example, at 110 baud, many devices require two stop
bits.
If PARENB is set, parity generation is enabled (a parity bit is added
to each output character). Furthermore, parity detection is enabled
(incoming characters are checked for the correct parity). If PARENB
is set, PARODD specifies odd parity if set; otherwise even parity is
used. If PARENB is clear, both parity generation and parity checking
are disabled.
If CREAD is set, the receiver is enabled. Otherwise no characters can
be received.
The specific effects of the HUPCL and CLOCAL bits depend on the mode
and type of the modem control in effect. See modem(7) for the
details.
If HUPCL is set, the modem control lines for the port are lowered
(disconnected) when the last process using the open port closes it or
terminates.
If CLOCAL is set, a connection does not depend on the state of the
modem status lines. If CLOCAL is clear, the modem status lines are
monitored.
Under normal circumstances, a call to read() waits for a modem
connection to complete. However, if either the O_NDELAY or the
O_NONBLOCK flags are set or CLOCAL is set, the open() returns
immediately without waiting for the connection. If CLOCAL is set, see
Modem Disconnect for the effects of read() and write() for those files
for which the connection has not been established or has been lost.
LOBLK is used by the shell layers facility (see shl(1)). The shell
layers facility is not part of the general terminal interface, and the
LOBLK bit is not examined by the general terminal interface.
The initial hardware control value after open is B300, CS8, CREAD, and
HUPCL.
Local Modes
The c_lflag field is used to control terminal functions.
ISIG Enable signals.
ICANON Canonical input (erase and kill processing).
XCASE Canonical upper/lower presentation.
ECHO Enable echo.
ECHOE Echo ERASE as correcting backspace sequence.
Hewlett-Packard Company - 16 - HP-UX Release 9.0: August 1992
termio(7) termio(7)
ECHOK Echo NL after kill character.
ECHONL Echo NL.
NOFLSH Disable flush after interrupt, quit, or suspend.
TOSTOP Send SIGTTOU for background output.
IEXTEN Enable extended functions.
If ISIG is set, each input character is checked against the special
control characters INTR, QUIT, SUSP, and DSUSP (see Process Group
Control IOCTL Commands). If an input character matches one of these
control characters, the function associated with that character is
performed and the character is discarded. If ISIG is clear, no
checking is done and the character is treated as a normal data
character. Thus these special input functions are possible only if
ISIG is set.
If ICANON is set, canonical processing is enabled. This enables the
erase and kill edit functions, and the assembly of input characters
into lines delimited by NL, EOF, or EOL. If ICANON is clear, read
requests are satisfied directly from the input queue. A read blocks
until at least MIN characters have been received or the timeout value
TIME has expired between characters. (See Non-Canonical Mode Input
Processing (MIN/TIME Interaction)). This allows fast bursts of input
to be read efficiently while still allowing single-character input.
The time value represents tenths of seconds.
If XCASE is set, and if ICANON and IEXTEN are set, an uppercase letter
is accepted on input by preceding it with a \ character, and is output
preceded by a \ character. In this mode, the following escape
sequences are generated on output and accepted on input:
tab(;); lB lB cf4 cf4. To obtain:;Use: `;\' |;\! {;\( };\) \;\\
For example, A is input as \a, \n as \\n, and \N as \\\n. XCASE would
normally be used in conjunction with IUCLC and OLCUC for terminals
that support only the first-sixty-four-character limited character
set. In this case, IUCLC processing is done before XCASE for input,
and processing is done after XCASE for output. Therefore typing A
causes an a to be read because of IUCLC, and typing \A causes an A to
be read since IUCLC produces \a which is turned into A by the XCASE
processing.
If ECHO is set, characters are echoed back to the terminal when
received. If ECHO is clear, characters are not echoed.
When ICANON is set, canonical processing is enabled. This enables the
erase and kill edit functions, and the assembly of input characters
into lines delimited by NL, EOF, and EOL, as described in Canonical
Mode Input Processing. Furthermore, the following echo functions are
possible. If ECHO and ECHOE are set, the erase character is echoed as
the three-character ASCII sequence BS SP BS, which clears the last
character from a CRT screen. If ECHOE is set and ECHO is clear, the
Hewlett-Packard Company - 17 - HP-UX Release 9.0: August 1992
termio(7) termio(7)
erase character is echoed as the two-character ASCII sequence SP BS,
which clears the current character from a CRT screen (the cursor
remains in the same position). If ECHOK is set, the NL character is
echoed after the kill character to emphasize that the line is being
deleted. If ECHONL is set, the NL character is echoed even if ECHO is
clear. This is useful for terminals set to local echo (that is, half
duplex). Unless escaped, the EOF character is not echoed. Because
ASCII EOT is the default EOF character, this prevents terminals that
respond to EOT from hanging up.
If NOFLSH is set, the normal flush of the input and output queues
associated with quit, interrupt, and suspend characters is not done.
However, NOFLSH does not affect the flushing of data upon receipt of a
break when BRKINT is set.
If the TOSTOP bit is set, an attempt by a process that is not in the
foreground process group to write to its controlling terminal will be
denied when the process is not ignoring and not blocking the SIGTTOU
signal. If the write is denied and the process is a member of an
orphaned process group write() returns -1 and sets errno to EIO and no
signal is sent. If the write is denied and the process is a not a
member of an orphaned process group, the SIGTTOU signal is sent to
that process group.
If ICANON is set, the ERASE, KILL, and EOF characters can be escaped
by a preceding \ character, in which case no special function is done.
If IEXTEN is set, IXANY, XCASE, and IUCLC functions are allowed.
IEXTEN does not affect any other functions.
The initial local control value is all-bits-clear.
Special Control Characters
Special control characters are defined in the array c_cc. All of
these special characters except START and STOP can be changed.
Attempts to change the START and STOP are ignored. The subscript name
and description for each element in both canonical and non-canonical
mode are shown in the following table.
tab(;); cB s s CBw(1.1i) CBw(1.3i) CB cp-1 cp-1 l. Subscript
Usage Canonical;;Non-Canonical;;Description _ VEOF;;EOF character
VEOL;;EOL character VERASE;;ERASE character VINTR;VINTR;INTR
character VKILL;;KILL character ;VMIN;MIN value VQUIT;VQUIT;QUIT
character VSTART;VSTART;START character VSTOP;VSTOP;STOP
character VSUSP;VSUSP;SUSP character ;VTIME;TIME value
termios Structure-Related Functions
The following functions are provided when using the termios structure.
Note that the effects on the terminal device do not become effective
until the tcsetattr() function is successfully called. Refer to the
appropriate manual entries for details.
Hewlett-Packard Company - 18 - HP-UX Release 9.0: August 1992
termio(7) termio(7)
tab(;); cB s lB lB lf4w(1.5i) l. termios Structure Functions
Function;Description _ cfgetospeed();get output baud rate
cfgetispeed();get input baud rate cfsetospeed();set output baud
rate cfsetispeed();set input baud rate tcgetattr();get terminal
state tcsetattr();set terminal state
termio Structure-Related IOCTL Commands
Several ioctl() system calls apply to terminal files that use the
termio structure (see termio Structure). If a requested command is
not recognized, the request returns -1 with errno set to EINVAL.
ioctl() system calls that reference the termio structure have the
form:
ioctl (fildes, command, arg)
struct termio *arg;
Commands using this form are:
TCGETA Get the parameters associated with the terminal
and store them in the termio structure referenced
by arg. This command is allowed from a background
process; however, the information may be
subsequently changed by a foreground process.
TCSETA Set the parameters associated with the terminal
from the structure referenced by arg. The change
is immediate. If characters are being output when
the command is requested, results are undefined
and the output may be garbled.
TCSETAW Wait for the output to drain before setting new
parameters. This form should be used when
changing parameters that affect output.
TCSETAF Wait for the output to drain, then flush the input
queue and set the new parameters.
termio Caveats
Only the first eight special control characters (see termios
Structure) can be set or returned. The values of indices VEOL and
VEOF are the same as indices VTIME and VMIN respectively. Hence if
ICANON is set, VEOL or VTIME is the additional end-of-line character
and VEOF or VMIN is the end-of-file character. If ICANON is clear,
VEOL or VTIME is the inter-character-timer value and VEOF or VMIN is
the minimum number of characters desired for reads.
The IEXTEN flag (see Local Modes) cannot be changed directly by
TCSETA, TCSETAW, or TCSETAF, nor can it be returned by TCGETA: This
flag is always considered set after a successful TCSETA, TCSETAF, or
TCSETAW command. This flag stays set and its function is performed
Hewlett-Packard Company - 19 - HP-UX Release 9.0: August 1992
termio(7) termio(7)
until a call that uses the termios structure specifically clears the
flag.
Structure-Independent Functions
The following functions which are independent of both the termio and
termios structures are provided for controlling terminals. Refer to
the appropriate manual entries for details.
tab(;); c s lB lB lf4w(1.2i) l. Structure-Independent Functions
Function;Description _ tcsendbreak();send a break tcdrain();wait
until output has drained tcflush();flush input or output queue or
both tcflow();suspend or resume input or output tcgetpgrp();get
foreground process group id tcsetpgrp();set foreground process
group id
System Asynchronous I/O IOCTL Commands
The following ioctl() system calls provide for system asynchronous I/O
and have the form:
ioctl (fildes, command, arg)
int *arg;
Commands using this form are:
FIOSSAIOSTAT If the integer referenced by arg is non-zero,
system asynchronous I/O is enabled; that is,
enable SIGIO to be sent to the process
currently designated with FIOSSAIOOWN (see
below) whenever the terminal device file
status changes from "no read data available"
to "read data available". If no process has
been designated with FIOSSAIOOWN, enable
SIGIO to be sent to the first process that
opened the terminal device file.
If the designated process has exited, the
SIGIO signal is not sent to any process.
If the integer referenced by arg is 0, system
asynchronous I/O is disabled.
The default on open of a terminal device file
is that system asynchronous I/O is disabled.
FIOGSAIOSTAT The integer referenced by arg is set to 1 if
system asynchronous I/O is enabled.
Otherwise, the integer referenced by arg is
set to 0.
FIOSSAIOOWN Set the process ID that will receive the
SIGIO signals due to system asynchronous I/O
Hewlett-Packard Company - 20 - HP-UX Release 9.0: August 1992
termio(7) termio(7)
to the value of the integer referenced by
arg. If no process can be found
corresponding to that specified by the
integer referenced by arg, the call returns
-1 with errno set to ESRCH. A user with
appropriate privileges can designate that any
process receive the SIGIO signals. If the
request is not made by a user with
appropriate privileges and the calling
process does not either designate that itself
or another process whose real, saved, or
effective user ID matches its real or
effective user ID or the calling process does
not designate a process that is a descendant
of the calling process to receive the SIGIO
signals, the call returns -1 with errno set
to EPERM.
If the designated process subsequently exits,
the SIGIO signal is not sent to any process.
The default on open of a terminal device file
is that the process performing the first open
is set to receive the SIGIO signals.
FIOGSAIOOWN The integer referenced by arg is set to the
process ID designated to receive SIGIO
signals.
Line Control IOCTL Commands
Several ioctl() system calls control input and output. Some of these
calls have the form:
ioctl (fildes, command, arg)
int *arg;
Commands using this form are:
TCSBRK Wait for the output to drain. If arg is 0, send a
break (zero bits for at least 0.25 seconds). The
tcsendbreak() function performs the same function
(see tcsendbreak(3C)).
TCXONC Start/stop control. If arg is 0, suspend output;
if 1, restart suspended output; if 2, transmit a
STOP character; if 3, transmit a START character.
If any other value is given for arg, the call
returns -1 with errno set to EINVAL. The tcflow()
function performs the same functions (see
tcflow(3C)).
Hewlett-Packard Company - 21 - HP-UX Release 9.0: August 1992
termio(7) termio(7)
TCFLSH If arg is 0, flush the input queue; if 1, flush
the output queue; if 2, flush both the input and
output queues. If any other value is given for
arg, the call returns -1 with errno set to EINVAL.
The tcflush() function performs the same functions
(see tcflush(3C)).
Sending a BREAK is accomplished by holding the
data transmit line at a SPACE or logical zero
condition for at least 0.25 seconds. During this
interval, data can be sent to the device, but
because of serial data interface limitations, the
BREAK takes precedence over all data. Thus, all
data sent to a device during a BREAK is lost.
This includes system-generated XON/XOFF characters
used for input flow control. Note also that a
delay in transmission of the XOFF flow control
character until after the BREAK is terminated
could still result in data overflow because the
flow control character may not be sent soon
enough.
Other calls have the form:
ioctl (fildes, command, arg)
long *arg;
Commands using this form are:
FIONREAD Returns in the long integer referenced by arg the
number of characters immediately readable from the
terminal device file. This command is allowed
from a background process; however, the data
itself cannot be read from a background process.
Non-blocking I/O IOCTL Commands
Non-blocking I/O is easily provided via the O_NONBLOCK and O_NDELAY
flags available in both open(2) and fcntl(2). The commands in this
section are provided for backward compatibility with previously
developed applications. ioctl() system calls that provide a style of
non-blocking I/O different from O_NONBLOCK and O_NDELAY have the form:
ioctl (fildes, command, arg)
long *arg;
Commands using this form are:
FIOSNBIO If the integer referenced by arg is non-zero,
FIOSNBIO-style non-blocking I/O is enabled; that
is, subsequent reads and writes to the terminal
device file are handled in a non-blocking manner
Hewlett-Packard Company - 22 - HP-UX Release 9.0: August 1992
termio(7) termio(7)
(see below). If the integer referenced by arg is
0, FIOSNBIO-style non-blocking I/O is disabled.
For reads, FIOSNBIO-style non-blocking I/O
prevents all read requests to that device file
from blocking, whether the requests succeed or
fail. Such a read request completes in one of
three ways:
o If there is enough data available to
satisfy the entire request, the read
completes successfully, having read all of
the data, and returns the number of
characters read;
o If there is not enough data available to
satisfy the entire request, the read
completes successfully, having read as
much data as possible, and returns the
number of characters read;
o If there is no data available, the read
returns -1 with errno set to EWOULDBLOCK.
For writes, FIOSNBIO-style non-blocking I/O
prevents all write requests to that device file
from blocking, whether the requests succeed or
fail. Such a write request completes in one of
three ways:
o If there is enough space available in the
system to buffer all the data, the write
completes successfully, having written out
all of the data, and returns the number of
characters written;
o If there is not enough space in the buffer
to write out the entire request, the write
completes successfully, having written as
much data as possible, and returns the
number of characters written;
o If there is no space in the buffer, the
write returns -1 with errno set to
EWOULDBLOCK.
To prohibit FIOSNBIO-style non-blocking I/O from
interfering with the O_NONBLOCK and O_NDELAY flags
(see open(2) and fcntl(2)), the functionality of
O_NONBLOCK and O_NDELAY always supersedes the
functionality of FIOSNBIO-style non-blocking I/O.
Hewlett-Packard Company - 23 - HP-UX Release 9.0: August 1992
termio(7) termio(7)
This means that if either O_NONBLOCK or O_NDELAY
is set, the driver performs read requests in
accordance with the definition of O_NDELAY or
O_NONBLOCK. When both O_NONBLOCK and O_NDELAY are
clear, the definition of FIOSNBIO-style non-
blocking I/O applies.
The default on open of a terminal device file is
that FIOSNBIO-style non-blocking I/O is disabled.
FIOGSNBIO The integer referenced by arg is set to 1, if
FIOSNBIO-style non-blocking I/O is enabled.
Otherwise, the integer referenced by arg is set to
0.
Process Group Control IOCTL Commands
The process group control features described here (except for setting
and getting the delayed stop process character) are easily implemented
using the functions tcgetattr(), tcsetattr(), tcgetpgrp(), and
tcsetpgrp() (see tcgetattr(2), tcsetattr(2), tcgetpgrp(3C), and
tcsetpgrp(3C) respectively).
The following structure, used with process group control, is defined
in <bsdtty.h>:
struct ltchars {
unsigned char t_suspc; /* stop process character */
unsigned char t_dsuspc; /* delayed stop process character */
unsigned char t_rprntc; /* reserved; must be '_POSIX_VDISABLE' */
unsigned char t_flushc; /* reserved; must be '_POSIX_VDISABLE' */
unsigned char t_werasc; /* reserved; must be '_POSIX_VDISABLE' */
unsigned char t_lnextc; /* reserved; must be '_POSIX_VDISABLE' */
};
The initial value for all these characters is _POSIX_VDISABLE, which
causes them to be disabled. The meaning for each character is as
follows:
t_suspc Suspend the foreground process group. A suspend
signal (SIGTSTP) is sent to all processes in the
foreground process group. Normally, each process
is forced to stop, but arrangements can be made to
either ignore or block the signal, or to receive a
trap to an agreed-upon location; see signal(2) and
signal(5). When enabled, the typical value for
this character is Control-Z or ASCII SUB. Setting
or getting t_suspc is equivalent to setting or
getting the SUSP special control character.
t_dsuspc Same as t_suspc, except that the suspend signal
(SIGTSTP) is sent when a process reads the
Hewlett-Packard Company - 24 - HP-UX Release 9.0: August 1992
termio(7) termio(7)
character, rather than when the character is
typed. When enabled, the typical value for this
character is Ctrl-Y or ASCII EM.
Attempts to set any of the reserved characters to a value other than
_POSIX_VDISABLE cause ioctl() to return -1 with errno set to EINVAL
with no change in value of the reserved character.
ioctl() system calls that use the above structure have the form:
ioctl (fildes, command, arg)
struct ltchars *arg;
Commands using this form are:
TIOCGLTC Get the process group control characters and store
them in the ltchars structure referenced by arg.
This command is allowed from a background process.
However, the information may be subsequently
changed by a foreground process.
TIOCSLTC Set the process group control characters from the
structure referenced by arg.
Additional process group control ioctl() system calls have the form:
ioctl (fildes, command, arg)
unsigned int *arg;
Commands using this form are:
TIOCGPGRP Returns in the integer referenced by arg the
foreground process group associated with the
terminal. This command is allowed from a
background process. However, the information may
be subsequently changed by a foreground process.
This feature is easily implemented using the
tcgetpgrp() function (see tcgetpgrp(3C)).
If the ioctl() call fails, it returns -1 and sets
errno to one of the following values:
[EBADF] fildes is not a valid file
descriptor.
[ENOTTY] The file associated with fildes
is not the controlling terminal,
or the calling process does not
have a controlling terminal.
Hewlett-Packard Company - 25 - HP-UX Release 9.0: August 1992
termio(7) termio(7)
[EACCES] The file associated with fildes
is the controlling terminal of
the calling process, however,
there is no foreground process
group defined for the controlling
terminal.
Note: EACCES may not be returned
in future releases. Behavior in
cases where no foreground process
group is defined for the
controlling terminal may change
in future versions of the POSIX
standard. Portable applications,
therefore, should not rely on
this error condition.
TIOCSPGRP Sets the foreground process group associated with
the terminal to the value referenced by arg. This
feature is easily implemented using the
tcsetpgrp() function (see tcsetpgrp(3C)).
If the ioctl() call fails, it returns -1 and sets
errno to one of the following values:
[EBADF] fildes is not a valid file
descriptor.
[EINVAL] The process ID referenced by arg
is not a supported value.
[ENOTTY] The calling process does not have
a controlling terminal, or the
fildes is not the controlling
terminal, or the controlling
terminal is no longer associated
with the session of the calling
process.
[EPERM] The process ID referenced by arg
is a supported value but does not
match the process group ID of a
process in the same session as
the calling process.
TIOCLGET Get the process group control mode word and store
it in the int referenced by arg. This command is
allowed from a background process; however, the
information may be subsequently changed by a
foreground process.
Hewlett-Packard Company - 26 - HP-UX Release 9.0: August 1992
termio(7) termio(7)
TIOCLSET Set the process group control mode word to the
value of the int referenced by arg.
TIOCLBIS Use the int referenced by arg as a mask of bits to
set in the process group control mode word.
TIOCLBIC Use the int referenced by arg as a mask of bits to
clear in the process group control mode word.
The following bit is defined in the process group control mode word:
LTOSTOP Send SIGTTOU for background writes.
Setting or clearing LTOSTOP is equivalent to setting or clearing the
TOSTOP flag (see Local Modes). If LTOSTOP is set and a process is not
in the foreground process group of its controlling terminal, a write
by the process to its controlling terminal may be denied (see Terminal
Access Control).
Terminal Size IOCTL Commands
The following ioctl() system calls are used to get and set terminal
size information for the terminal referenced by fildes. These ioctl()
system calls use the winsize structure to get and set the terminal
size information. The winsize structure, defined in <termios.h>, has
the following members :
unsigned short ws_row; /* Rows, in characters */
unsigned short ws_col; /* Columns, in characters */
unsigned short ws_xpixel; /* Horizontal size, in pixels */
unsigned short ws_ypixel; /* Vertical size, in pixels */
The initial values for all elements of terminal size are zero. The
values for terminal size are neither set nor used by the general
terminal interface, and have no effect on the functionality of the
general terminal interface. The values for terminal size are set and
used only by applications that access them through the terminal-size
ioctl() system calls (see ioctl(2)).
ioctl() system calls that use the above structure have the form:
ioctl (fildes, command, arg)
struct winsize *arg;
Commands using this form are:
TIOCGWINSZ Get the terminal size values and store them in the
winsize structure referenced by arg. This command
is allowed from a background process.
TIOCSWINSZ Set the terminal size values from the winsize
structure referenced by arg. If any of the new
Hewlett-Packard Company - 27 - HP-UX Release 9.0: August 1992
termio(7) termio(7)
values differ from previous values, a SIGWINCH
signal is sent to all processes in the terminal's
foreground process group.
WARNINGS
Various HP-UX implementations use non-serial interfaces that look like
terminals (such as bit-mapped graphics displays) or ``smart cards''
that cannot implement the exact capabilities described above.
Therefore, not all systems can exactly meet the standard stated above.
Each implementation is required to state any deviations from the
standard as part of its system-specific documentation.
FIOSSAIOSTAT is similar to BSD 4.2 FIOASYNC, with the
addition of provisions for security.
FIOGSAIOSTAT is of HP origin, complements FIOSSAIOSTAT,
and allows saving and restoring system
asynchronous I/O TTY states for command
interpreter processes.
FIOSSAIOOWN is similar to BSD 4.2 FIOSETOWN, with
additional provisions for security.
FIOGSAIOOWN is similar to BSD FIOGETOWN. 4.2 Note also
the difference that the BSD 4.2 version of
this functionality used process groups, while
the HP-UX version only uses processes.
FIOSNBIO is the same as BSD FIONBIO, 4.2 except that
it does not interfere with the O_NDELAY or
O_NONBLOCK open() and fcntl() flags.
FIOGNBIO is of HP origin, complements FIOSNBIO, and
allows saving and restoring the FIOSNBIO
-style non-blocking I/O TTY state for command
interpreter processes.
DEPENDENCIES
Series 300/400
Data loss can occur with HP 98626/98644 serial interfaces and the
built-in serial interface of the Model 318, 319, 320, 330, 332, R/332,
340, 350, 360, V/360, and 370 if the effective combined data rate for
all installed serial interfaces exceeds 2400 baud (for example, two
interfaces running at 1200 baud and a third at 300 baud is equivalent
to 2700 baud combined).
HP 98626/98644 serial interfaces and the built-in Series 300 serial
interfaces of the Models listed above do not support 38400 baud.
HP 98642/98638 serial interfaces do not support 200 and 38400 baud.
The second and third (select code 5,6) serial interfaces of Series 400
Hewlett-Packard Company - 28 - HP-UX Release 9.0: August 1992
termio(7) termio(7)
machines support no bit rates above 19200. On the Model 425e, this
also applies to the first (sc 9) port.
Built-in serial ports on the Series 400 machines (except Model 425e)
support the following additional baud rate settings: 57600, 115200,
230400, and 460800 baud. An RS-232-to-RS-422 converter may be
required to achieve practical cable lengths at these baud rates
(because RS-232 only specifies up to 19200 baud).
The c_iflag field parameter IXANY (enable any character to restart
output) is not supported by the HP 98628A interface card.
Timed delays are not supported.
The HP 98628A interface does not support the following baud rates:
900, 7200, 38400.
Built-in serial ports on Series 400s and 400t machines and Series 300
models 332, 345, 375, 380, 382, and R/382 have both RTS and CTS flow
control capability as well as a configurable receive FIFO trigger
level and transmit limit.
RTS/CTS hardware handshaking can be enabled through a bit in the
device file minor number, through an ioctl() call (see termiox(7)), or
through the stty command (see stty(1)).
The receive FIFO trigger level is configurable through two bits in the
device file minor number. The receive FIFO trigger level is used to
set the level at which a receive interrupt is generated to the system.
Setting a smaller value for the receive FIFO trigger level enables the
system to react more quickly to receipt of characters. However, using
a smaller trigger level increases system overhead to process the
additional interrupts. A higher receive FIFO trigger level reduces
the system interrupt overhead for heavy inbound data traffic at the
cost of less time for the system to read data from the hardware before
receive FIFOs are overrun. When using RTS flow control, the receive
FIFO trigger level also determines the point at which the hardware
lowers RTS to protect the receive FIFO. Use of a higher receive FIFO
trigger level also reduces XOFF flow control responsiveness because,
under light inbound data flow conditions, receipt of the XOFF
character by the system is slightly delayed. Choice of the
appropriate receive FIFO trigger level should be based upon how the
serial port is to be used. For most applications a receive FIFO
trigger level of 8 (c3,c2 = 10) is suggested.
Two bits in the device file minor number specify the transmit limit,
the number of characters which are successively loaded into the
transmit FIFO. Setting a smaller transmit limit allows the
transmitter to be more responsive to flow control either from receipt
of an XOFF character or de-assertion of CTS at the cost of increased
system interrupt overhead. Setting a larger transmit limit reduces
Hewlett-Packard Company - 29 - HP-UX Release 9.0: August 1992
termio(7) termio(7)
interrupt overhead but is not as responsive to flow control since the
remainder of the transmit FIFO can be transmitted even after the
transmitter is flow controlled. When communicating with devices which
have little tolerance for data receipt after flow control, one must
choose the transmit limit appropriately.
Series 300/400 device file minor number:
Series 300/400 device file minor numbers take the form:
0xScAdCM
where:
Sc = Two hexadecimal digits (8 bits) to indicate the select
code of the serial hardware.
Ad = Two hexadecimal digits (8 bits) to indicate port address.
(HP 98642 and HP 98638 only)
C = One hexadecimal digit (4 bits) for FIFO control on the
enhanced serial ports mentioned above. Values for each
bit are as follows:
center box tab(;); cB s s | cB s s cB | cB |
cB | cB | cB | cB c | c | c | c | c | c . Receive
FIFO Trigger Level;Transmit Limit _
c ;c ;Level;c ;c ;Limit
3 2 1 0
_ 0;0;1;0;0;1 0;1;4;0;1;4 1;0;8;1;0;8 1;1;14;1;1;12
M = One hexadecimal digit (4 bits) to determine hardware flow
state and port access type. Values for each bit are as
follows:
center box tab(;); cB | cBw(3i) c | l. Bit;Value _
m ;RTS/CTS hardware flow control ;(0 = OFF, 1 = ON) m ;0
3 2
= modem, 1 = direct connect m ;0 = Simple protocol
1
(U.S.), ;1 = CCITT protocol (Europe) m ;0 = dial-in
0
modem, 1 = dial-out modem
Series 700
Built-in serial ports on Series 700 machines support the following
additional baud rate settings: 57600, 115200, 230400, and 460800 baud.
An RS-232-to-RS-422 converter may be required to achieve practical
cable lengths at these baud rates (because RS-232 only specifies up to
19200 baud).
Timed delays are not supported.
Built-in serial ports on Series 700 systems have RTS and CTS flow
control capability, configurable receive FIFO trigger levels, and a
Hewlett-Packard Company - 30 - HP-UX Release 9.0: August 1992
termio(7) termio(7)
configurable transmit limit. RTS/CTS hardware handshaking can be
enabled through a bit in the device file minor number, through an
ioctl() call (see termiox(7)), or through the stty command (see
stty(1)). The discussion of receive FIFO trigger levels and transmit
limits in the Series 300/400 section above also applies to built-in
serial ports on Series 700 systems.
Series 700 device file minor number:
Series 700 device file minor numbers take the form:
0xScF0CM
where:
Sc = Two hexadecimal digits (8 bits) to indicate the select
code of the serial hardware. This is always 0x20.
F = One hexadecimal digit (4 bits) to specify the function
number for the port (4 for port A, 5 for port B).
C = One hexadecimal digit (4 bits) for FIFO control. Values
for each bit are as follows (same as Series 300/400):
center box tab(;); cB s s | cB s s cB | cB |
cB | cB | cB | cB c | c | c | c | c | c . Receive
FIFO Trigger Level;Transmit Limit _
c ;c ;Level;c ;c ;Limit
3 2 1 0
_ 0;0;1;0;0;1 0;1;4;0;1;4 1;0;8;1;0;8 1;1;14;1;1;12
M = One hexadecimal digit (4 bits) to determine hardware flow
state and port access type. Values for each bit are as
follows:
center box tab(;); cB | cBw(3i) c | l. Bit;Value _
m ;RTS/CTS hardware flow control ;(0 = OFF, 1 = ON) m ;0
3 2
= modem, 1 = direct connect m ;0 = Simple protocol
1
(U.S.), ;1 = CCITT protocol (Europe) m ;0 = dial-in
0
modem, 1 = dial-out modem
Series 800
Timed output delays are not directly supported. If used, an
appropriate number of fill characters (based on the current baud rate)
is output. The total time to output the fill characters is at least
as long as the time requested.
The system specified input flow control values are as follows: low
water mark is 60, high water mark is 180, and maximum allowed input is
512.
Hewlett-Packard Company - 31 - HP-UX Release 9.0: August 1992
termio(7) termio(7)
The HP 98196A (formerly 27140A option 800) interface does not support
the following hardware settings:
CBAUD B200, B38400, EXTA, EXTB.
The HP A1703-60003 and the HP 28639-60001 interfaces do not support
baud rates above 9600. Furthermore, changing the following hardware
settings on port 0 from the default (9600 baud, 8 bit characters, 1
stop bit, no parity) is not supported:
CBAUD CSIZE, CSTOPB, PARENB, PARODD.
The HP J2094A interface supports RTS and CTS flow control. The
RTS/CTS hardware handshaking can be enabled through a bit in the
device file minor number, through an ioctl() call (see termiox(7)), or
through the stty command (see stty(1)). The device file minor number
bits have the following meanings:
Series 800 device file minor number:
Series 800 device file minor numbers take the form:
0xMHLuAD
where:
M = One hexadecimal digit (4 bits) for the port access type.
Values for each bit are as follows:
center box tab(;); cB | cBw(3i) c | l. Bit;Value _
m ;Must be zero (0) m ;0 = Simple protocol (U.S.), ;1 =
3 2
CCITT protocol (Europe) m m ;00 = Direct ;01 = Dial-out
1 0
modem ;10 = Dial-in modem ;11 = Invalid
H = One hexadecimal digit (4 bits) to determine hardware flow
control (HP J2094A only). Values for each bit are as
follows (bits 3, 1, and 0 must be 0):
center box tab(;); cB | cBw(3i) c | l. m m m m ;Value
3 2 1 0
_ 0000;RTS/CTS hardware flow control OFF 0100;RTS/CTS
hardware flow control ON
Lu = Two hexadecimal digits (8 bits) to indicate the logical
unit of the serial interface.
ad = Two hexadecimal digits (8 bits) to indicate the port
number of this device on the serial interface.
AUTHOR
termios was developed HP and the IEEE Computer Society.
termio was developed by HP, AT&T, and the University of California,
Hewlett-Packard Company - 32 - HP-UX Release 9.0: August 1992
termio(7) termio(7)
Berkeley.
FILES
/dev/console
/dev/tty*
SEE ALSO
shl(1), stty(1), mknod(1M), fork(2), ioctl(2), setsid(2), signal(2),
stty(2), setpgid(2), blmode(3C), cfspeed(3C), tccontrol(3C),
tcattribute(3C), tcgetpgrp(3C), tcsetpgrp(3C) signal(5), unistd(5),
sttyV6(7), tty(7), modem(7), termiox(7).
STANDARDS CONFORMANCE
termio: SVID2, XPG2
termios: AES, XPG3, XPG4, FIPS 151-2, POSIX.1
Hewlett-Packard Company - 33 - HP-UX Release 9.0: August 1992