termios.4

早期freebsd实现

.\" Copyright (c) 1991, 1992, 1993
.\"	The Regents of the University of California.  All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"	This product includes software developed by the University of
.\"	California, Berkeley and its contributors.
.\" 4. Neither the name of the University nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\"	@(#)termios.4	8.4 (Berkeley) 4/19/94
.\"
.Dd April 19, 1994
.Dt TERMIOS 4
.Os BSD 4
.Sh NAME
.Nm termios
.Nd general terminal line discipline
.Sh SYNOPSIS
.Fd #include <termios.h>
.Sh DESCRIPTION
This describes a general terminal line discipline that is
supported on tty asynchronous communication ports.
.Ss Opening a Terminal Device File
When a terminal file is opened, it normally causes the process to wait
until a connection is established.  For most hardware, the presence
of a connection is indicated by the assertion of the hardware
.Dv CARRIER line.
If the termios structure associated with the terminal file has the
.Dv CLOCAL
flag set in the cflag, or if the
.Dv O_NONBLOCK
flag is set
in the
.Xr open 2
call, then the open will succeed even without
a connection being present.
In practice, applications
seldom open these files; they are opened by special programs, such
as
.Xr getty 2
or
.Xr rlogind 2 ,
and become
an application's standard input, output, and error files.
.Ss Job Control in a Nutshell
Every process is associated with a particular process group and session.
The grouping is hierarchical: every member of a particular process group is a
member of the same session.  This structuring is used in managing groups
of related processes for purposes of
.\" .Gw "job control" ;
.Em "job control" ;
that is, the
ability from the keyboard (or from program control) to simultaneously
stop or restart
a complex command (a command composed of one or more related
processes).  The grouping into process groups allows delivering
of signals that stop or start the group as a whole, along with
arbitrating which process group has access to the single controlling
terminal.  The grouping at a higher layer into sessions is to restrict
the job control related signals and system calls to within processes
resulting from a particular instance of a "login".  Typically, a session
is created when a user logs in, and the login terminal is setup
to be the controlling terminal; all processes spawned from that
login shell are in the same session, and inherit the controlling
terminal.
A job control shell
operating interactively (that is, reading commands from a terminal)
normally groups related processes together by placing them into the
same process group.  A set of processes in the same process group
is collectively referred to as a "job". When the foreground process
group of the terminal is the same as the process group of a particular
job, that job is said to be in the "foreground".  When the process
group of the terminal is different than the process group of
a job (but is still the controlling terminal), that job is said
to be in the "background".  Normally the
shell reads a command and starts the job that implements that
command.  If the command is to be started in the foreground (typical), it
sets the process group of the terminal to the process group
of the started job, waits for the job to complete, and then
sets the process group of the terminal back to its own process
group (it puts itself into the foreground).  If the job is to
be started in the background (as denoted by the shell operator "&"),
it never changes the process group of the terminal and doesn't
wait for the job to complete (that is, it immediately attempts to read the next
command).  If the job is started in the foreground, the user may
type a key (usually
.Ql \&^Z )
which generates the terminal stop signal
.Pq Dv SIGTSTP
and has the affect of stopping the entire job.
The shell will notice that the job stopped, and will resume running after
placing itself in the foreground.
The shell also has commands for placing stopped jobs in the background,
and for placing stopped or background jobs into the foreground.
.Ss Orphaned Process Groups
An orphaned process group is a process group that has no process
whose parent is in a different process group, yet is in the same
session.  Conceptually it means a process group that doesn't have
a parent that could do anything if it were to be stopped.  For example,
the initial login shell is typically in an orphaned process group.
Orphaned process groups are immune to keyboard generated stop
signals and job control signals resulting from reads or writes to the
controlling terminal.
.Ss The Controlling Terminal
A terminal may 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 may be the controlling terminal for at
most one session.  The controlling terminal for a session is allocated by
the session leader by issuing the
.Dv TIOCSCTTY
ioctl.  A controlling terminal
is never acquired by merely opening a terminal device file.
When a controlling terminal becomes
associated with a session, its foreground process group is set to
the process group of the session leader.
.Pp
The controlling terminal is inherited by a child process during a
.Xr fork 2
function call.  A process relinquishes its controlling terminal when it
creates a new session with the
.Xd setsid 2
function; other processes
remaining in the old session that had this terminal as their controlling
terminal continue to have it.
A process does not relinquish its
controlling terminal simply by closing all of its file descriptors
associated with the controlling terminal if other processes continue to
have it open.
.Pp
When a controlling process terminates, the controlling terminal is
disassociated from the current session, allowing it to be acquired by a
new session leader.  Subsequent access to the terminal by other processes
in the earlier session will be denied, with attempts to access the
terminal treated as if modem disconnect had been sensed.
.Ss Terminal Access Control
If a process is in the foreground process group of its controlling
terminal, read operations are allowed.
Any attempts by a process
in a background process group to read from its controlling terminal
causes a
.Dv SIGTTIN
signal to be sent to
the process's group
unless one of the
following special cases apply:  If the reading process is ignoring or
blocking the
.Dv SIGTTIN signal, or if the process group of the reading
process is orphaned, the
.Xr read 2
returns -1 with
.Va errno set to
.Er Dv EIO
and no
signal is sent.  The default action of the
.Dv SIGTTIN
signal is to stop the
process to which it is sent.
.Pp
If a process is in the foreground process group of its controlling
terminal, write operations are allowed.
Attempts by a process in a background process group to write to its
controlling terminal will cause the process group to be sent a
.Dv SIGTTOU
signal unless one of the following special cases apply:  If
.Dv TOSTOP
is not
set, or if
.Dv TOSTOP
is set and the process is ignoring or blocking the
.Dv SIGTTOU
signal, the process is allowed to write to the terminal and the
.Dv SIGTTOU
signal is not sent.  If
.Dv TOSTOP
is set, and the process group of
the writing process is orphaned, and the writing process is not ignoring
or blocking
.Dv SIGTTOU ,
the
.Xr write
returns -1 with
errno set to
.Er Dv EIO
and no signal is sent.
.Pp
Certain calls that set terminal parameters are treated in the same
fashion as write, except that
.Dv TOSTOP
is ignored; that is, the effect is
identical to that of terminal writes when
.Dv TOSTOP
is set.
.Ss Input Processing and Reading Data
A terminal device associated with a terminal device file may operate in
full-duplex mode, so that data may arrive even while output is occurring.
Each terminal device file has associated with it an input queue, into
which incoming data is stored by the system before being read by a
process.  The system imposes a limit,
.Pf \&{ Dv MAX_INPUT Ns \&} ,
on the number of
bytes that may be stored in the input queue.  The behavior of the system
when this limit is exceeded depends on the setting of the
.Dv IMAXBEL
flag in the termios
.Fa c_iflag .
If this flag is set, the terminal
is sent an
.Tn ASCII
.Dv BEL
character each time a character is received
while the input queue is full.  Otherwise, the input queue is flushed
upon receiving the character.
.Pp
Two general kinds of input processing are available, determined by
whether the terminal device file is in canonical mode or noncanonical
mode. Additionally,
input characters are processed according to the
.Fa c_iflag
and
.Fa c_lflag
fields.  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 can operate in full-duplex mode.
.Pp
The manner in which data is provided to a process reading from a terminal
device file is dependent on whether the terminal device file is in
canonical or noncanonical mode.
.Pp
Another dependency is whether the
.Dv O_NONBLOCK
flag is set by
.Xr open()
or
.Xr fcntl() .
If the
.Dv O_NONBLOCK
flag is clear, then the read request is
blocked until data is available or a signal has been received.  If the
.Dv O_NONBLOCK
flag is set, then the read request is completed, without
blocking, in one of three ways:
.Bl -enum -offset indent
.It
If there is enough data available to satisfy the entire request,
and the read completes successfully the number of
bytes read is returned.
.It
If there is not enough data available to satisfy the entire
request, and the read completes successfully, having read as
much data as possible, the number of bytes read is returned.
.It
If there is no data available, the read returns -1, with
errno set to
.Er EAGAIN .
.El
.Pp
When data is available depends on whether the input processing mode is
canonical or noncanonical.
.Ss Canonical Mode Input Processing
In canonical mode input processing, terminal input is processed in units
of lines.  A line is delimited by a newline
.Ql \&\en
character, an end-of-file
.Pq Dv EOF
character, or an end-of-line
.Pq Dv EOL
character.  See the
.Sx "Special Characters"
section for
more information on
.Dv EOF
and
.Dv EOL .
This means that a read request will
not return until an entire line has been typed, or a signal has been
received.  Also, no matter how many bytes are requested in the read call,
at most one line is returned.  It is not, however, necessary to
read a whole line at once; any number of bytes, even one, may be
requested in a read without losing information.
.Pp
.Pf \&{ Dv MAX_CANON Ns \&}
is a limit on the
number of bytes in a line.
The behavior of the system when this limit is
exceeded is the same as when the input queue limit
.Pf \&{ Dv MAX_INPUT Ns \&} ,
is exceeded.
.Pp
Erase and kill processing occur when either of two special characters,
the
.Dv ERASE
and
.Dv KILL
characters (see the
.Sx "Special Characters section" ) ,
is received.
This processing affects data in the input queue that has not yet been
delimited by a newline
.Dv NL,
.Dv EOF ,
or
.Dv EOL
character.  This un-delimited
data makes up the current line.  The
.Dv ERASE
character deletes the last
character in the current line, if there is any.  The
.Dv KILL
character
deletes all data in the current line, if there is any.  The
.Dv ERASE
and
.Dv KILL
characters have no effect if there is no data in the current line.
The
.Dv ERASE
and
.Dv KILL
characters themselves are not placed in the input
queue.
.Ss Noncanonical Mode Input Processing
In noncanonical mode input processing, input bytes are not assembled into
lines, and erase and kill processing does not occur.  The values of the
.Dv MIN
and
.Dv TIME
members of the
.Fa c_cc
array are used to determine how to
process the bytes received.
.Pp
.Dv MIN
represents the minimum number of bytes that should be received when
the
.Xr read
function successfully returns.
.Dv TIME
is a timer of 0.1 second
granularity that is used to time out bursty and short term data
transmissions.  If
.Dv MIN
is greater than
.Dv \&{ Dv MAX_INPUT Ns \&} ,
the response to the
request is undefined.  The four possible values for
.Dv MIN
and
.Dv TIME
and
their interactions are described below.
.Ss "Case A: MIN > 0, TIME > 0"
In this case
.Dv TIME
serves as an inter-byte timer and is activated after
the first byte is received.  Since it is an inter-byte timer, it is reset
after a byte is received.  The interaction between
.Dv MIN
and
.Dv TIME
is as
follows:  as soon as one byte is received, the inter-byte timer is
started.  If
.Dv MIN
bytes are received before the inter-byte timer expires
(remember that the timer is reset upon receipt of each byte), the read is
satisfied.  If the timer expires before
.Dv MIN
bytes are received, the
characters received to that point are returned to the user.  Note that if
.Dv TIME
expires at least one byte is returned because the timer would
not have been enabled unless a byte was received.  In this case
.Pf \&( Dv MIN
> 0,
.Dv TIME
> 0) the read blocks until the
.Dv MIN
and
.Dv TIME
mechanisms are
activated by the receipt of the first byte, or a signal is received.  If
data is in the buffer at the time of the read(), the result is as
if data had been received immediately after the read().
.Ss "Case B: MIN > 0, TIME = 0"
In this case, since the value of
.Dv TIME
is zero, the timer plays no role
and only
.Dv MIN
is significant.  A pending read is not satisfied until
.Dv MIN
bytes are received (i.e., the pending read blocks until
.Dv MIN
bytes
are received), or a signal is received.  A program that uses this case to
read record-based terminal
.Dv I/O
may block indefinitely in the read
operation.
.Ss "Case C: MIN = 0, TIME > 0"
In this case, since
.Dv MIN
= 0,
.Dv TIME
no longer represents an inter-byte
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
byte is received or the read timer expires.  Note that in this case if
the timer expires, no bytes are returned.  If the timer does not
expire, the only way the read can be satisfied is if a byte is received.
In this case the read will not block indefinitely waiting for a byte; if
no byte is received within
.Dv TIME Ns *0.1
seconds after the read is initiated,
the read returns a value of zero, having read no data.  If data is
in the buffer at the time of the read, the timer is started as if
data had been received immediately after the read.
.Ss Case D: MIN = 0, TIME = 0
The minimum of either the number of bytes requested or the number of
bytes currently available is returned without waiting for more
bytes to be input.  If no characters are available, read returns a
value of zero, having read no data.
.Ss Writing Data and Output Processing
When a process writes one or more bytes to a terminal device file, they
are processed according to the
.Fa c_oflag
field (see the
.Sx "Output Modes
section).  The
implementation may provide a buffering mechanism; as such, when a call to
write() completes, all of the bytes written have been scheduled for
transmission to the device, but the transmission will not necessarily
have been completed.
.\" See also .Sx "6.4.2" for the effects of
.\" .Dv O_NONBLOCK
.\" on write.
.Ss Special Characters
Certain characters have special functions on input or output or both.
These functions are summarized as follows:
.Bl -tag -width indent
.It Dv INTR
Special character on input and is recognized if the
.Dv ISIG
flag (see the
.Sx "Local Modes"
section) is enabled.  Generates a
.Dv SIGINT
signal which is sent to all processes in the foreground