Ioctl Requests termio(7I)
NAME
termio - general terminal interface
SYNOPSIS
#include
ioctl(int fildes, int request, struct termio *arg);
ioctl(int fildes, int request, int arg);
#include
ioctl(int fildes, int request, struct termios *arg);
DESCRIPTION
This release supports a general interface for asynchronous
communications ports that is hardware-independent. The user
interface to this functionality is using function calls (the
preferred interface) described in termios(3C) or ioctl com-
mands described in this section. This section also discusses
the common features of the terminal subsystem which are
relevant with both user interfaces.
When a terminal file is opened, it normally causes the pro-
cess to wait until a connection is established. In practice,
user programs seldom open terminal files; they are opened by
the system and become a user's standard input, output, and
error files. The first terminal file opened by the session
leader that is not already associated with a session becomes
the controlling terminal for that session. The controlling
terminal plays a special role in handling quit and interrupt
signals, as discussed below. The controlling terminal is
inherited by a child process during a fork(2). A process can
break this association by changing its session using set-
sid() (see setsid(2)).
A terminal associated with one of these files ordinarily
operates in full-duplex mode. Characters may be typed at any
time, even while output is occurring, and are only lost when
the character input buffers of the system become completely
full, which is rare. For example, the number of characters
in the line discipline buffer may exceed {MAXCANON} and
IMAXBEL (see below) is not set, or the user may accumulate {
MAXINPUT} number of input characters that have not yet been
read by some program. When the input limit is reached, all
the characters saved in the buffer up to that point are
thrown away without notice.
SunOS 5.11 Last change: 14 Sep 2005 1
Ioctl Requests termio(7I)
Session Management (Job Control)
A control terminal will distinguish one of the process
groups in the session associated with it to be the fore-
ground process group. All other process groups in the ses-
sion are designated as background process groups. This fore-
ground process group plays a special role in handling
signal-generating input characters, as discussed below. By
default, when a controlling terminal is allocated, the con-
trolling process's process group is assigned as foreground
process group.
Background process groups in the controlling process's ses-
sion are subject to a job control line discipline when they
attempt to access their controlling terminal. Process groups
can be sent signals that will cause them to stop, unless
they have made other arrangements. An exception is made for
members of orphaned process groups.
An orphaned process group is one where the process group
(see getpgid(2)) has no members with a parent in a different
process group but sharing the same controlling terminal.
When a member of an orphaned process group attempts to
access its controlling terminal, EIO is returned because
there would be no way to restart the process if it were
stopped on one of these signals.
If a member of a background process group attempts to read
its controlling terminal, its process group will be sent a
SIGTIN signal, which will normally cause the members of
that process group to stop. If, however, the process is
ignoring or holding SIGTIN, or is a member of an orphaned
process group, the read will fail with errno set to EIO,
and no signal is sent.
If a member of a background process group attempts to write
its controlling terminal and the TOSTOP bit is set in the
clflag field, its process group is sent a SIGTOU signal,
which will normally cause the members of that process group
to stop. If, however, the process is ignoring or holding
SIGTOU, the write will succeed. If the process is not
ignoring or holding SIGTOU and is a member of an orphaned
process group, the write will fail with errno set to EIO,
and no signal will be sent.
If TOSTOP is set and a member of a background process group
attempts to ioctl its controlling terminal, and that ioctl
will modify terminal parameters (for example, TCSETA,
SunOS 5.11 Last change: 14 Sep 2005 2
Ioctl Requests termio(7I)
TCSETAW, TCSETAF, or TIOCSPGRP), its process group will be
sent a SIGTOU signal, which will normally cause the members
of that process group to stop. If, however, the process is
ignoring or holding SIGTOU, the ioctl will succeed. If the
process is not ignoring or holding SIGTOU and is a member
of an orphaned process group, the write will fail with
errno set to EIO, and no signal will be sent.
Canonical Mode Input Processing
Normally, terminal input is processed in units of lines. A
line is delimited by a newline (ASCI LF) character, an
end-of-file (ASCI EOT) character, or an end-of-line charac-
ter. This means that a program attempting to read will block
until an entire line has been typed. Also, no matter how
many characters are requested in the read call, at most one
line will be returned. It is not necessary, however, to read
a whole line at once; any number of characters may be
requested in a read, even one, without losing information.
During input, erase and kill processing is normally done.
The ERASE character (by default, the character DEL) erases
the last character typed. The WERASE character (the charac-
ter Control-w) erases the last "word" typed in the current
input line (but not any preceding spaces or tabs). A "word"
is defined as a sequence of non-blank characters, with tabs
counted as blanks. Neither ERASE nor WERASE will erase
beyond the beginning of the line. The KIL character (by
default, the character NAK) kills (deletes) the entire input
line, and optionally outputs a newline character. All these
characters operate on a key stroke basis, independent of any
backspacing or tabbing that may have been done. The REPRINT
character (the character Control-r) prints a newline fol-
lowed by all characters that have not been read. Reprinting
also occurs automatically if characters that would normally
be erased from the screen are fouled by program output. The
characters are reprinted as if they were being echoed;
consequencely, if ECHO is not set, they are not printed.
The ERASE and KIL characters may be entered literally by
preceding them with the escape character. In this case, the
escape character is not read. The erase and kill characters
may be changed.
Non-canonical Mode Input Processing
In non-canonical mode input processing, input characters are
not assembled into lines, and erase and kill processing does
not occur. The MIN and TIME values are used to determine how
to process the characters received.
SunOS 5.11 Last change: 14 Sep 2005 3
Ioctl Requests termio(7I)
MIN represents the minimum number of characters that should
be received when the read is satisfied (that is, when the
characters are returned to the user). TIME is a timer of
0.10-second granularity that is used to timeout bursty and
short-term data transmissions. The four possible values for
MIN and TIME and their interactions are described below.
Case A: MIN > 0, TIME > 0 In this case, TIME serves as an
intercharacter timer and is
activated after the first char-
acter is received. Since it is
an intercharacter timer, it is
reset after a character is
received. The interaction
between MIN and TIME is as fol-
lows: as soon as one character
is received, the intercharacter
timer is started. If MIN char-
acters are received before the
intercharacter timer expires
(note that the timer is reset
upon receipt of each charac-
ter), the read is satisfied.
If the timer expires before MIN
characters are received, the
characters received to that
point are returned to the user.
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 sleeps
until the MIN and TIME mechan-
isms are activated by the
receipt of the first character.
If the number of characters
read is less than the number of
characters available, the timer
is not reactivated and the sub-
sequent read is satisfied
immediately.
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 charac-
ters are received (the pending
read sleeps until MIN
SunOS 5.11 Last change: 14 Sep 2005 4
Ioctl Requests termio(7I)
characters are received). A
program that uses this case to
read record based terminal I/O
may block indefinitely in the
read operation.
Case C: MIN = 0, TIME > 0 In this case, since MIN = 0,
TIME no longer represents an
intercharacter timer: it now
serves as a read timer that is
activated as soon as a read is
done. A read is satisfied as
soon as a single character is
received or the read timer
expires. Note that, in this
case, if the timer expires, no
character is returned. If the
timer does not expire, the only
way the read can be satisfied
is if a character is received.
In this case, the read will not
block indefinitely waiting for
a character; if no character is
received within TIME *.10
seconds after the read is ini-
tiated, the read returns with
zero characters.
Case D: MIN = 0, TIME = 0 In this case, return is immedi-
ate. The minimum of either the
number of characters requested
or the number of characters
currently available is returned
without waiting for more char-
acters to be input.
Comparing Different Cases of MIN, TIME Interaction
Some points to note about MIN and TIME :
o In the following explanations, note that 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.
o Also note that in case A (MIN > 0, TIME > 0), TIME
represents an intercharacter timer, whereas in
SunOS 5.11 Last change: 14 Sep 2005 5
Ioctl Requests termio(7I)
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 (for example, file transfer programs),
where a program would like to process at least MIN charac-
ters at a time. In case A, the intercharacter timer is
activated by a user as a safety measure; in case B, the
timer 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, whereas 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 pro-
gram does a read of 20 bytes, MIN is 10, and 25 characters
are present, then 20 characters will be returned to the
user.
Writing Characters
When one or more characters are written, they are transmit-
ted to the terminal as soon as previously written characters
have finished typing. Input characters are echoed as they
are typed if echoing has been enabled. If a process produces
characters more rapidly than they can be typed, it will be
suspended when its output queue exceeds some limit. When the
queue is drained down to some threshold, the program is
resumed.
Special Characters
Certain characters have special functions on input. These
functions and their default character values are summarized
as follows:
INTR (Control-c or ASCI ETX) generates a SIGINT sig-
nal. SIGINT is sent to all foreground processes
associated with the controlling terminal. Nor-
mally, each such process is forced to terminate,
but arrangements may be made either to ignore the
signal or to receive a trap to an agreed upon
location. (See signal.h(3HEAD)).
QUIT (Control- or ASCI FS) generates a SIGQUIT sig-
nal. Its treatment is identical to the interrupt
SunOS 5.11 Last change: 14 Sep 2005 6
Ioctl Requests termio(7I)
signal except that, unless a receiving process
has made other arrangements, it will not only be
terminated but a core image file (called core)
will be created in the current working directory.
ERASE (DEL) erases the preceding character. It does not
erase beyond the start of a line, as delimited by
a NL, EOF, EOL, or EOL2 character.
WERASE (Control-w or ASCI ETX) erases the preceding
"word". It does not erase beyond the start of a
line, as delimited by a NL, EOF, EOL, or EOL2
character.
KIL (Control-u or ASCI NAK) deletes the entire line,
as delimited by a NL, EOF, EOL, or EOL2 charac-
ter.
REPRINT (Control-r or ASCI DC2) reprints all characters,
preceded by a newline, that have not been read.
EOF (Control-d or ASCI EOT) may be used to generate
an end-of-file from a terminal. When received,
all the characters waiting to be read are immedi-
ately passed to the program, without waiting for
a newline, and the EOF is discarded. Thus, if no
characters are waiting (that is, the EOF occurred
at the beginning of a line) zero characters are
passed back, which is the standard end-of-file
indication. Unless escaped, the EOF character is
not echoed. Because EOT is the default EOF char-
acter, this prevents terminals that respond to
EOT from hanging up.
NL (ASCI LF) is the normal line delimiter. It can-
not be changed or escaped.
EOL (ASCI NUL) is an additional line delimiter,
like NL . It is not normally used.
EOL2 is another additional line delimiter.
SunOS 5.11 Last change: 14 Sep 2005 7
Ioctl Requests termio(7I)
SWTCH (Control-z or ASCI EM) Header file symbols
related to this special character are present for
compatibility purposes only and the kernel takes
no special action on matching SWTCH (except to
discard the character).
SUSP (Control-z or ASCI SUB) generates a SIGTSTP
signal. SIGTSTP stops all processes in the fore-
ground process group for that terminal.
DSUSP (Control-y or ASCI EM). It generates a SIGTSTP
signal as SUSP does, but the signal is sent when
a process in the foreground process group
attempts to read the DSUSP character, rather than
when it is typed.
STOP (Control-s or ASCI DC3) can be used to suspend
output temporarily. It is useful with CRT termi-
nals to prevent output from disappearing before
it can be read. While output is suspended, STOP
characters are ignored and not read.
START (Control-q or ASCI DC1) is used to resume out-
put. Output has been suspended by a STOP charac-
ter. While output is not suspended, START char-
acters are ignored and not read.
DISCARD (Control-o or ASCI SI) causes subsequent output
to be discarded. Output is discarded until
another DISCARD character is typed, more input
arrives, or the condition is cleared by a pro-
gram.
LNEXT (Control-v or ASCI SYN) causes the special mean-
ing of the next character to be ignored. This
works for all the special characters mentioned
above. It allows characters to be input that
would otherwise be interpreted by the system (for
example KIL, QUIT). The character values for
INTR, QUIT, ERASE, WERASE, KIL, REPRINT, EOF,
EOL, EOL2, SWTCH, SUSP, DSUSP, STOP, START, DIS-
CARD, and LNEXT may be changed to suit individual
tastes. If the value of a special control charac-
ter is POSIXVDISABLE (0), the function of that
special control character is disabled. The ERASE,
KIL, and EOF characters may be escaped by a
SunOS 5.11 Last change: 14 Sep 2005 8
Ioctl Requests termio(7I)
preceding backslash (\) character, in which case
no special function is done. Any of the special
characters may be preceded by the LNEXT charac-
ter, in which case no special function is done.
Modem Disconnect
When a modem disconnect is detected, a SIGHUP signal is sent
to the terminal's controlling process. Unless other arrange-
ments have been made, these signals cause the process to
terminate. If SIGHUP is ignored or caught, any subsequent
read returns with an end-of-file indication until the termi-
nal is closed.
If the controlling process is not in the foreground process
group of the terminal, a SIGTSTP is sent to the terminal's
foreground process group. Unless other arrangements have
been made, these signals cause the processes to stop.
Processes in background process groups that attempt to
access the controlling terminal after modem disconnect while
the terminal is still allocated to the session will receive
appropriate SIGTOU and SIGTIN signals. Unless other
arrangements have been made, this signal causes the
processes to stop.
The controlling terminal will remain in this state until it
is reinitialized with a successful open by the controlling
process, or deallocated by the controlling process.
Terminal Parameters
The parameters that control the behavior of devices and
modules providing the termios interface are specified by
the termios structure defined by termios.h. Several
ioctl(2) system calls that fetch or change these parameters
use this structure that contains the following members:
tcflagt ciflag; /* input modes */
tcflagt coflag; /* output modes */
tcflagt ccflag; /* control modes */
tcflagt clflag; /* local modes */
cct ccc[NCS]; /* control chars */
The special control characters are defined by the array
ccc. The symbolic name NCS is the size of the Control-
character array and is also defined by . The
relative positions, subscript names, and typical default
SunOS 5.11 Last change: 14 Sep 2005 9
Ioctl Requests termio(7I)
values for each function are as follows:
SunOS 5.11 Last change: 14 Sep 2005 10
Ioctl Requests termio(7I)
Relative Position Subscript Name Typical Default Value
0 VINTR ETX
1 VQUIT FS
2 VERASE DEL
3 VKIL NAK
4 VEOF EOT
5 VEOL NUL
6 VEOL2 NUL
7 VWSTCH NUL
8 VSTART NUL
9 VSTOP DC3
10 VSUSP SUB
11 VDSUSP EM
12 VREPRINT DC2
13 VDISCARD SI
14 VWERASE ETB
15 VLNEXT SYN
16-19 Reserved
Input Modes
The ciflag field describes the basic terminal input con-
trol:
IGNBRK Ignore break condition.
BRKINT Signal interrupt on break.
IGNPAR Ignore characters with parity errors.
SunOS 5.11 Last change: 14 Sep 2005 11
Ioctl Requests termio(7I)
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 upper-case to lower-case on input.
IXON Enable start/stop output control.
IXANY Enable any character to restart output.
IXOF Enable start/stop input control.
IMAXBEL Echo BEL on input line too long.
If IGNBRK is set, a break condition (a character framing
error with data all zeros) detected on input is ignored,
that is, not put on the input queue and therefore not read
by any process. If IGNBRK is not set and BRKINT is set, the
break condition shall flush 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' (ASCI NUL) character, or if PARMRK is set, as
'\377', '\0', c, where '\377' is a single character with
value 377 octal (0xff hex, 255 decimal), '\0' is a single
character with value 0, and c is the errored character
received.
If IGNPAR is set, a byte with framing or parity errors
(other than break) is ignored.
SunOS 5.11 Last change: 14 Sep 2005 12
Ioctl Requests termio(7I)
If PARMRK is set, and IGNPAR is not set, a byte with a fram-
ing or parity error (other than break) is given to the
application as the three-character sequence: '\377', '\0',
c, where '\377' is a single character with value 377 octal
(0xff hex, 255 decimal), '\0' is a single character with
value 0, and c is the errored character received. To avoid
ambiguity in this case, if ISTRIP is not set, a valid char-
acter of '\377' is given to the application as `\377.' If
neither IGNPAR nor PARMRK is set, a framing or parity error
(other than break) is given to the application as a single
'\0' (ASCI NUL) character.
If INPCK is set, input parity checking is enabled. If INPCK
is not set, input parity checking is disabled. This allows
output parity generation without input parity errors. Note
that whether input parity checking is enabled or disabled is
independent of whether parity detection is enabled or dis-
abled. If parity detection 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 is set correctly or
not.
If ISTRIP is set, valid input characters are first stripped
to seven bits, otherwise all eight 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). Otherwise, if ICRNL is set, a
received CR character is translated into a NL character.
If IUCLC is set, a received upper case, alphabetic character
is translated into the corresponding lower case character.
If IXON is set, start/stop output control is enabled. A
received STOP character suspends output and a received START
character restarts output. The STOP and START characters
will not be read, but will merely perform flow control
functions. If IXANY is set, any input character restarts
output that has been suspended.
If IXOF is set, the system transmits a STOP character when
the input queue is nearly full, and a START character when
enough input has been read so that the input queue is nearly
empty again.
SunOS 5.11 Last change: 14 Sep 2005 13
Ioctl Requests termio(7I)
If IMAXBEL is set, the ASCI BEL character is echoed if the
input stream overflows. Further input is not stored, but any
input already present in the input stream is not disturbed.
If IMAXBEL is not set, no BEL character is echoed, and all
input present in the input queue is discarded if the input
stream overflows.
Output Modes
The coflag field specifies the system treatment of out-
put:
OPOST Post-process output.
OLCUC Map lower case to upper 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.
OFIL Use fill characters for delay.
OFDEL Fill is DEL, else NUL.
NLDLY Select newline delays:
NL0
NL1
CRDLY Select carriage-return delays:
CR0
CR1
CR2
CR3
TABDLY Select horizontal tab delays or tab expansion:
TAB0
SunOS 5.11 Last change: 14 Sep 2005 14
Ioctl Requests termio(7I)
TAB1
TAB2
TAB3 Expand tabs to spaces
XTABS Expand tabs to spaces
BSDLY Select backspace delays:
BS0
BS1
VTDLY Select vertical tab delays:
VT0
VT1
FDLY Select form feed delays:
F0
F1
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 lower case alphabetic character is
transmitted as the corresponding upper case 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 ONRET is set, the NL character is assumed to do the
carriage-return function; the column pointer is set to 0 and
the delays specified for CR are used. Otherwise, the NL
character is assumed to do just the line-feed function; the
column pointer remains unchanged. The column pointer is also
set to 0 if the CR character is actually transmitted.
SunOS 5.11 Last change: 14 Sep 2005 15
Ioctl Requests termio(7I)
The delay bits specify how long transmission stops to allow
for mechanical or other movement when certain characters are
sent to the terminal. In all cases, a value of 0 indicates
no delay. If OFIL 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 it is
NUL.
If a form-feed or vertical-tab delay is specified, it lasts
for about 2 seconds.
Newline delay lasts about 0.10 seconds. If ONLRET is set,
the carriage-return delays are used instead of the newline
delays. If OFIL is set, two fill characters are transmit-
ted.
Carriage-return delay type 1 is dependent on the current
column position, type 2 is about 0.10 seconds, and type 3 is
about 0.15 seconds. If OFIL is set, delay type 1 transmits
two fill characters, and type 2 transmits four fill charac-
ters.
Horizontal-tab delay type 1 is dependent on the current
column position. Type 2 is about 0.10 seconds. Type 3 speci-
fies that tabs are to be expanded into spaces. If OFIL is
set, two fill characters are transmitted for any delay.
Backspace delay lasts about 0.05 seconds. If OFIL is set,
one fill character is transmitted.
The actual delays depend on line speed and system load.
Control Modes
The ccflag field describes the hardware control of the ter-
minal:
CBAUD Baud rate:
B0 Hang up
B50 50 baud
SunOS 5.11 Last change: 14 Sep 2005 16
Ioctl Requests termio(7I)
B75 75 baud
B110 110 baud
B134 134 baud
B150 150 baud
B200 200 baud
B300 300 baud
B600 600 baud
B1200 1200 baud
B1800 1800 baud
B2400 2400 baud
B4800 4800 baud
B9600 9600 baud
B19200 19200 baud
EXTA External A
B38400 38400 baud
EXTB External B
B57600 57600 baud
SunOS 5.11 Last change: 14 Sep 2005 17
Ioctl Requests termio(7I)
B76800 76800 baud
B115200 115200 baud
B153600 153600 baud
B230400 230400 baud
B307200 307200 baud
B460800 460800 baud
CSIZE Character size:
CS5 5 bits
CS6 6 bits
CS7 7 bits
CS8 8 bits
CSTOPB Send two stop bits, else one
CREAD Enable receiver
PARENB Parity enable
PAROD Odd parity, else even
HUPCL Hang up on last close
CLOCAL Local line, else dial-up
SunOS 5.11 Last change: 14 Sep 2005 18
Ioctl Requests termio(7I)
CIBAUD Input baud rate, if different from output rate
PAREXT Extended parity for mark and space parity
CRTSXOF Enable inbound hardware flow control
CRTSCTS Enable outbound hardware flow control
CBAUDEXT Bit to indicate output speed > B38400
CIBAUDEXT Bit to indicate input speed > B38400
The CBAUD bits together with the CBAUDEXT bit specify the
output baud rate. To retrieve the output speed from the ter-
mios structure pointed to by termiosp see the following
code segment.
speedt ospeed;
if (termiosp->ccflag & CBAUDEXT)
ospeed = (termiosp->ccflag & CBAUD) ] CBAUD ] 1;
else
ospeed = termiosp->ccflag & CBAUD;
To store the output speed in the termios structure pointed
to by termiosp see the following code segment.
speedt ospeed;
if (ospeed > CBAUD) {
termiosp->ccflag = CBAUDEXT;
ospeed -= (CBAUD ] 1);
} else
termiosp->ccflag &= ~CBAUDEXT;
termiosp->ccflag =
(termiosp->ccflag & ~CBAUD) (ospeed & CBAUD);
The zero baud rate, B0, is used to hang up the connection.
If B0 is specified, the data-terminal-ready signal is not
asserted. Normally, this disconnects the line.
SunOS 5.11 Last change: 14 Sep 2005 19
Ioctl Requests termio(7I)
If the CIBAUDEXT or CIBAUD bits are not zero, they specify
the input baud rate, with the CBAUDEXT and CBAUD bits speci-
fying the output baud rate; otherwise, the output and input
baud rates are both specified by the CBAUDEXT and CBAUD
bits. The values for the CIBAUD bits are the same as the
values for the CBAUD bits, shifted left IBSHIFT bits. For
any particular hardware, impossible speed changes are
ignored. To retrieve the input speed in the termios struc-
ture pointed to by termiosp see the following code seg-
ment.
speedt ispeed;
if (termiosp->ccflag & CIBAUDEXT)
ispeed = ((termiosp->ccflag & CIBAUD) >> IBSHIFT)
] (CIBAUD >> IBSHIFT) ] 1;
else
ispeed = (termiosp->ccflag & CIBAUD) >> IBSHIFT;
To store the input speed in the termios structure pointed
to by termiosp see the following code segment.
speedt ispeed;
if (ispeed == 0) {
ispeed = termiosp->ccflag & CBAUD;
if (termiosp->ccflag & CBAUDEXT)
ispeed ]= (CBAUD ] 1);
}
if ((ispeed << IBSHIFT) > CIBAUD) {
termiosp->ccflag = CIBAUDEXT;
ispeed -= ((CIBAUD >> IBSHIFT) ] 1);
} else
termiosp->ccflag &= ~CIBAUDEXT;
termiosp->ccflag =
(termiosp->ccflag & ~CIBAUD)
((ispeed << IBSHIFT) & CIBAUD);
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 is used. For example, at 110
baud, two stops bits are required.
If PARENB is set, parity generation and detection is
enabled, and a parity bit is added to each character. If
parity is enabled, the PAROD flag specifies odd parity if
set; otherwise, even parity is used.
SunOS 5.11 Last change: 14 Sep 2005 20
Ioctl Requests termio(7I)
If CREAD is set, the receiver is enabled. Otherwise, no
characters are received.
If HUPCL is set, the line is disconnected when the last pro-
cess with the line open closes it or terminates. That is,
the data-terminal-ready signal is not asserted.
If CLOCAL is set, the line is assumed to be a local, direct
connection with no modem control; otherwise, modem control
is assumed.
If CRTSXOF is set, inbound hardware flow control is
enabled.
If CRTSCTS is set, outbound hardware flow control is
enabled.
The four possible combinations for the state of CRTSCTS and
CRTSXOF bits and their interactions are described below.
Case A: CRTSCTS off, CRTSXOF off. In this case the
hardware flow control is disabled.
Case B: CRTSCTS on, CRTSXOF off. In this case only out-
bound hardware flow control is enabled. The state
of CTS signal is used to do outbound flow con-
trol. It is expected that output will be
suspended if CTS is low and resumed when CTS is
high.
Case C: CRTSCTS off, CRTSXOF on. In this case only
inbound hardware flow control is enabled. The
state of RTS signal is used to do inbound flow
control. It is expected that input will be
suspended if RTS is low and resumed when RTS is
high.
Case D: CRTSCTS on, CRTSXOF on. In this case both
inbound and outbound hardware flow control are
enabled. Uses the state of CTS signal to do out-
bound flow control and RTS signal to do inbound
flow control.
SunOS 5.11 Last change: 14 Sep 2005 21
Ioctl Requests termio(7I)
Local Modes
The clflag field of the argument structure is used by the
line discipline to control terminal functions. The basic
line discipline provides the following:
ISIG Enable signals.
ICANON Canonical input (erase and kill processing).
XCASE Canonical upper/lower presentation.
ECHO Enable echo.
ECHOE Echo erase character as BS-SP-BS &.
ECHOK Echo NL after kill character.
ECHONL Echo NL .
NOFLSH Disable flush after interrupt or quit.
TOSTOP Send SIGTOU for background output.
ECHOCTL Echo control characters as char, delete as ^?.
ECHOPRT Echo erase character as character erased.
ECHOKE BS-SP-BS erase entire line on line kill.
FLUSHO Output is being flushed.
PENDIN Retype pending input at next read or input char-
acter.
IEXTEN Enable extended (implementation-defined) func-
tions.
SunOS 5.11 Last change: 14 Sep 2005 22
Ioctl Requests termio(7I)
If ISIG is set, each input character is checked against the
special control characters INTR, QUIT, SWTCH, SUSP, STATUS,
and DSUSP. If an input character matches one of these con-
trol characters, the function associated with that character
is performed. (Note: If SWTCH is set and the character
matches, the character is simply discarded. No other action
is taken.) If ISIG is not set, no checking is done. 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-c, EOF, EOL,
and EOL . If ICANON is not set, read requests are satisfied
directly from the input queue. A read is not satisfied until
at least MIN characters have been received or the timeout
value TIME has expired between characters. 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 ICANON is set, an upper case letter is
accepted on input if preceded by a backslash (\) character,
and is output preceded by a backslash (\) character. In
this mode, the following escape sequences are generated on
output and accepted on input:
SunOS 5.11 Last change: 14 Sep 2005 23
Ioctl Requests termio(7I)
FOR: USE:
` \'
\!
~ \^
{ \(
} \)
\ \\
For example, input A as \a, \n as \\n, and \N as \\\n.
If ECHO is set, characters are echoed as received.
When ICANON is set, the following echo functions are possi-
ble.
o If ECHO and ECHOE are set, and ECHOPRT is not set,
the ERASE and WERASE characters are echoed as one
or more ASCI BS SP BS, which clears the last
character(s) from a CRT screen.
o If ECHO, ECHOPRT, and IEXTEN are set, the first
ERASE and WERASE character in a sequence echoes as
a backslash (\), followed by the characters being
erased. Subsequent ERASE and WERASE characters
echo the characters being erased, in reverse order.
The next non-erase character causes a `/' (slash)
to be typed before it is echoed. ECHOPRT should be
used for hard copy terminals.
o If ECHOKE and IEXTEN are set, the kill character
is echoed by erasing each character on the line
from the screen (using the mechanism selected by
ECHOE and ECHOPRa).
o If ECHOK is set, and ECHOKE is not set, the NL
character is echoed after the kill character to
emphasize that the line is deleted. Note that a `'
(escape) character or an LNEXT character preceding
the erase or kill character removes any special
function.
SunOS 5.11 Last change: 14 Sep 2005 24
Ioctl Requests termio(7I)
o If ECHONL is set, the NL character is echoed even
if ECHO is not set. This is useful for terminals
set to local echo (so called half-duplex).
If ECHOCTL and IEXTEN are set, all control characters (char-
acters with codes between 0 and 37 octal) other than ASCI
TAB, ASCI NL, the START character, and the STOP character,
ASCI CR, and ASCI BS are echoed as ^ X, where X is the
character given by adding 100 octal to the code of the con-
trol character (so that the character with octal code 1 is
echoed as ^ A), and the ASCI DEL character, with code 177
octal, is echoed as ^ ?.
If NOFLSH is set, the normal flush of the input and output
queues associated with the INTR, QUIT, and SUSP characters
is not done. This bit should be set when restarting system
calls that read from or write to a terminal (see sigac-
tion(2)).
If TOSTOP and IEXTEN are set, the signal SIGTOU is sent
to a process that tries to write to its controlling terminal
if it is not in the foreground process group for that termi-
nal. This signal normally stops the process. Otherwise, the
output generated by that process is output to the current
output stream. Processes that are blocking or ignoring
SIGTOU signals are excepted and allowed to produce output,
if any.
If FLUSHO and IEXTEN are set, data written to the terminal
is discarded. This bit is set when the FLUSH character is
typed. A program can cancel the effect of typing the FLUSH
character by clearing FLUSHO.
If PENDIN and IEXTEN are set, any input that has not yet
been read is reprinted when the next character arrives as
input. PENDIN is then automatically cleared.
If IEXTEN is set, the following implementation-defined func-
tions are enabled: special characters ( WERASE, REPRINT,
DISCARD, and LNEXT) and local flags ( TOSTOP, ECHOCTL,
ECHOPRT, ECHOKE, FLUSHO, and PENDIN).
Minimum and Timeout
The MIN and TIME values were described previously, in the
subsection, Non-canonical Mode Input Processing. The initial
value of MIN is 1, and the initial value of TIME is 0.
SunOS 5.11 Last change: 14 Sep 2005 25
Ioctl Requests termio(7I)
Terminal Size
The number of lines and columns on the terminal's display is
specified in the winsize structure defined by sys/termios.h
and includes the following members:
unsigned short wsrow; /* rows, in characters */
unsigned short wscol; /* columns, in characters */
unsigned short wsxpixel; /* horizontal size, in pixels */
unsigned short wsypixel; /* vertical size, in pixels */
Termio Structure
The SunOS/SVR4 termio structure is used by some ioctls; it
is defined by sys/termio.h and includes the following
members:
unsigned short ciflag; /* input modes */
unsigned short coflag; /* output modes */
unsigned short ccflag; /* control modes */
unsigned short clflag; /* local modes */
char cline; /* line discipline */
unsigned char ccc[NC]; /* control chars */
The special control characters are defined by the array
ccc. The symbolic name NC is the size of the Control-
character array and is also defined by termio.h. The rela-
tive positions, subscript names, and typical default values
for each function are as follows:
SunOS 5.11 Last change: 14 Sep 2005 26
Ioctl Requests termio(7I)
Relative Positions Subscript Names Typical Default Values
0 VINTR EXT
1 VQUIT FS
2 VERASE DEL
3 VKIL NAK
4 VEOF EOT
5 VEOL NUL
6 VEOL2 NUL
7 Reserved
The MIN values is stored in the VMIN element of the ccc
array; the TIME value is stored in the VTIME element of the
ccc array. The VMIN element is the same element as the
VEOF element; the VTIME element is the same element as the
VEOL element.
The calls that use the termio structure only affect the
flags and control characters that can be stored in the ter-
mio structure; all other flags and control characters are
unaffected.
Modem Lines
On special files representing serial ports, modem control
lines can be read. Control lines (if the underlying
hardware supports it) may also be changed. Status lines are
read-only. The following modem control and status lines may
be supported by a device; they are defined by sys/termios.h:
TIOCMLE line enable
TIOCMDTR data terminal ready
TIOCMRTS request to send
TIOCMST secondary transmit
SunOS 5.11 Last change: 14 Sep 2005 27
Ioctl Requests termio(7I)
TIOCMSR secondary receive
TIOCMCTS clear to send
TIOCMCAR carrier detect
TIOCMRNG ring
TIOCMDSR data set ready
TIOCMCD is a synonym for TIOCMCAR, and TIOCMRI is a
synonym for TIOCMRNG. Not all of these are necessarily sup-
ported by any particular device; check the manual page for
the device in question.
The software carrier mode can be enabled or disabled using
the TIOCSOFTCAR ioctl. If the software carrier flag for a
line is off, the line pays attention to the hardware carrier
detect (DCD) signal. The tty device associated with the line
cannot be opened until DCD is asserted. If the software car-
rier flag is on, the line behaves as if DCD is always
asserted.
The software carrier flag is usually turned on for locally
connected terminals or other devices, and is off for lines
with modems.
To be able to issue the TIOCGSOFTCAR and TIOCSOFTCAR ioctl
calls, the tty line should be opened with ONDELAY so that
the open(2) will not wait for the carrier.
Default Values
The initial termios values upon driver open is configur-
able. This is accomplished by setting the "ttymodes" pro-
perty in the file /kernel/drv/options.conf. Since this pro-
perty is assigned during system initialization, any change
to the "ttymodes" property will not take effect until the
next reboot. The string value assigned to this property
should be in the same format as the output of the stty(1)
command with the -g option.
SunOS 5.11 Last change: 14 Sep 2005 28
Ioctl Requests termio(7I)
If this property is undefined, the following termios modes
are in effect. The initial input control value is BRKINT,
ICRNL, IXON, IMAXBEL. The initial output control value is
OPOST, ONLCR, TAB3. The initial hardware control value is
B9600, CS8, CREAD. The initial line-discipline control value
is ISIG, ICANON, IEXTEN, ECHO, ECHOK, ECHOE, ECHOKE,
ECHOCTL.
IOCTLS
The ioctls supported by devices and STREAMS modules provid-
ing the termios(3C) interface are listed below. Some calls
may not be supported by all devices or modules. The func-
tionality provided by these calls is also available through
the preferred function call interface specified on termios.
TCGETS The argument is a pointer to a termios
structure. The current terminal parameters
are fetched and stored into that structure.
TCSETS The argument is a pointer to a termios
structure. The current terminal parameters
are set from the values stored in that
structure. The change is immediate.
TCSETSW The argument is a pointer to a termios
structure. The current terminal parameters
are set from the values stored in that
structure. The change occurs after all char-
acters queued for output have been transmit-
ted. This form should be used when changing
parameters that affect output.
TCSETSF The argument is a pointer to a termios
structure. The current terminal parameters
are set from the values stored in that
structure. The change occurs after all char-
acters queued for output have been transmit-
ted; all characters queued for input are
discarded and then the change occurs.
TCGETA The argument is a pointer to a termio struc-
ture. The current terminal parameters are
fetched, and those parameters that can be
stored in a termio structure are stored into
that structure.
SunOS 5.11 Last change: 14 Sep 2005 29
Ioctl Requests termio(7I)
TCSETA The argument is a pointer to a termio
structure. Those terminal parameters that
can be stored in a termio structure are set
from the values stored in that structure.
The change is immediate.
TCSETAW The argument is a pointer to a termio struc-
ture. Those terminal parameters that can be
stored in a termio structure are set from
the values stored in that structure. The
change occurs after all characters queued
for output have been transmitted. This form
should be used when changing parameters that
affect output.
TCSETAF The argument is a pointer to a termio struc-
ture. Those terminal parameters that can be
stored in a termio structure are set from
the values stored in that structure. The
change occurs after all characters queued
for output have been transmitted; all char-
acters queued for input are discarded and
then the change occurs.
TCSBRK The argument is an int value. Wait for the
output to drain. If the argument is 0, then
send a break (zero valued bits for 0.25
seconds).
TCXONC Start/stop control. The argument is an int
value. If the argument is 0, suspend output;
if 1, restart suspended output; if 2,
suspend input; if 3, restart suspended
input.
TCFLSH The argument is an int value. If the argu-
ment is 0, flush the input queue; if 1,
flush the output queue; if 2, flush both the
input and output queues.
TIOCGPGRP The argument is a pointer to a pidt. Set
the value of that pidt to the process
group ID of the foreground process group
associated with the terminal. See
termios(3C) for a description of TCGETPGRP.
SunOS 5.11 Last change: 14 Sep 2005 30
Ioctl Requests termio(7I)
TIOCSPGRP The argument is a pointer to a pidt. Asso-
ciate the process group whose process group
ID is specified by the value of that pidt
with the terminal. The new process group
value must be in the range of valid process
group ID values. Otherwise, the error
EPERM is returned.
TIOCGSID The argument is a pointer to a pidt. The
session ID of the terminal is fetched and
stored in the pidt.
TIOCGWINSZ The argument is a pointer to a winsize
structure. The terminal driver's notion of
the terminal size is stored into that struc-
ture.
TIOCSWINSZ The argument is a pointer to a winsize
structure. The terminal driver's notion of
the terminal size is set from the values
specified in that structure. If the new
sizes are different from the old sizes, a
SIGWINCH signal is set to the process group
of the terminal.
TIOCMBIS The argument is a pointer to an int whose
value is a mask containing modem control
lines to be turned on. The control lines
whose bits are set in the argument are
turned on; no other control lines are
affected.
TIOCMBIC The argument is a pointer to an int whose
value is a mask containing modem control
lines to be turned off. The control lines
whose bits are set in the argument are
turned off; no other control lines are
affected.
TIOCMGET The argument is a pointer to an int. The
current state of the modem status lines is
fetched and stored in the int pointed to by
the argument.
SunOS 5.11 Last change: 14 Sep 2005 31
Ioctl Requests termio(7I)
TIOCMSET The argument is a pointer to an int con-
taining a new set of modem control lines.
The modem control lines are turned on or
off, depending on whether the bit for that
mode is set or clear.
TIOCSPS The argument is a pointer to an int that
determines whether pulse-per-second event
handling is to be enabled (non-zero) or dis-
abled (zero). If a one-pulse-per-second
reference clock is attached to the serial
line's data carrier detect input, the local
system clock will be calibrated to it. A
clock with a high error, that is, a devia-
tion of more than 25 microseconds per tick,
is ignored.
TIOCGPS The argument is a pointer to an int, in
which the state of the even handling is
returned. The int is set to a non-zero value
if pulse-per-second (PS) handling has been
enabled. Otherwise, it is set to zero.
TIOCGSOFTCAR The argument is a pointer to an int whose
value is 1 or 0, depending on whether the
software carrier detect is turned on or off.
TIOCSOFTCAR The argument is a pointer to an int whose
value is 1 or 0. The value of the integer
should be 0 to turn off software carrier, or
1 to turn it on.
TIOCGPSEV The argument is a pointer to a struct
ppsclockev. This structure contains the fol-
lowing members:
struct timeval tv;
uint32t serial;
"tv" is the system clock timestamp when the
event (pulse on the DCD pin) occurred.
"serial" is the ordinal of the event, which
each consecutive event being assigned the
next ordinal. The first event registered
gets a "serial" value of 1. The TIOCGPSEV
returns the last event registered; multiple
calls will persistently return the same
SunOS 5.11 Last change: 14 Sep 2005 32
Ioctl Requests termio(7I)
event until a new one is registered. In
addition to time stamping and saving the
event, if it is of one-second period and of
consistently high accuracy, the local system
clock will automatically calibrate to it.
FILES
Files in or under /dev
SEE ALSO
stty(1), fork(2), getpgid(2), getsid(2), ioctl(2), set-
sid(2), sigaction(2), signal(3C), tcsetpgrp(3C),
termios(3C), signal.h(3HEAD), streamio(7I)
SunOS 5.11 Last change: 14 Sep 2005 33
|
