terminal.texi

一个C源代码分析器

@node Low-Level Terminal Interface
@chapter Low-Level Terminal Interface

This chapter describes functions that are specific to terminal devices.
You can use these functions to do things like turn off input echoing;
set serial line characteristics such as line speed and flow control; and
change which characters are used for end-of-file, command-line editing,
sending signals, and similar control functions.

Most of the functions in this chapter operate on file descriptors.
@xref{Low-Level I/O}, for more information about what a file
descriptor is and how to open a file descriptor for a terminal device.

@menu
* Is It a Terminal::            How to determine if a file is a terminal
			         device, and what its name is.
* I/O Queues::                  About flow control and typeahead.
* Canonical or Not::            Two basic styles of input processing.
* Terminal Modes::              How to examine and modify flags controlling
			         details of terminal I/O: echoing,
                                 signals, editing. 
* Line Control::                Sending break sequences, clearing
                                 terminal buffers @dots{} 
* Noncanon Example::            How to read single characters without echo.
@end menu

@node Is It a Terminal
@section Identifying Terminals
@cindex terminal identification
@cindex identifying terminals

The functions described in this chapter only work on files that
correspond to terminal devices.  You can find out whether a file
descriptor is associated with a terminal by using the @code{isatty}
function.

@pindex unistd.h
Prototypes for both @code{isatty} and @code{ttyname} are declared in
the header file @file{unistd.h}.

@comment unistd.h
@comment POSIX.1
@deftypefun int isatty (int @var{filedes})
This function returns @code{1} if @var{filedes} is a file descriptor
associated with an open terminal device, and @code{0} otherwise.
@end deftypefun

If a file descriptor is associated with a terminal, you can get its
associated file name using the @code{ttyname} function.  See also the
@code{ctermid} function, described in @ref{Identifying the Terminal}.

@comment unistd.h
@comment POSIX.1
@deftypefun {char *} ttyname (int @var{filedes})
If the file descriptor @var{filedes} is associated with a terminal
device, the @code{ttyname} function returns a pointer to a
statically-allocated, null-terminated string containing the file name of
the terminal file.  The value is a null pointer if the file descriptor
isn't associated with a terminal, or the file name cannot be determined.
@end deftypefun

@node I/O Queues
@section I/O Queues

Many of the remaining functions in this section refer to the input and
output queues of a terminal device.  These queues implement a form of
buffering @emph{within the kernel} independent of the buffering
implemented by I/O streams (@pxref{I/O on Streams}).

@cindex terminal input queue
@cindex typeahead buffer
The @dfn{terminal input queue} is also sometimes referred to as its
@dfn{typeahead buffer}.  It holds the characters that have been received
from the terminal but not yet read by any process.

The size of the terminal's input queue is described by the
@code{_POSIX_MAX_INPUT} and @code{MAX_INPUT} parameters; see @ref{Limits
for Files}.  You are guaranteed a queue size of at least
@code{MAX_INPUT}, but the queue might be larger, and might even
dynamically change size.  If input flow control is enabled by setting
the @code{IXOFF} input mode bit (@pxref{Input Modes}), the terminal
driver transmits STOP and START characters to the terminal when
necessary to prevent the queue from overflowing.  Otherwise, input may
be lost if it comes in too fast from the terminal.  In canonical mode,
all input stays in the queue until a newline character is received, so
the terminal input queue can fill up when you type a very long line.
@xref{Canonical or Not}.

@cindex terminal output queue
The @dfn{terminal output queue} is like the input queue, but for output;
it contains characters that have been written by processes, but not yet
transmitted to the terminal.  If output flow control is enabled by
setting the @code{IXON} input mode bit (@pxref{Input Modes}), the
terminal driver obeys STOP and STOP characters sent by the terminal to
stop and restart transmission of output.

@dfn{Clearing} the terminal input queue means discarding any characters
that have been received but not yet read.  Similarly, clearing the
terminal output queue means discarding any characters that have been
written but not yet transmitted.

@node Canonical or Not
@section Two Styles of Input: Canonical or Not

POSIX systems support two basic modes of input: canonical and
noncanonical.

@cindex canonical input processing
In @dfn{canonical input processing} mode, terminal input is processed in
lines terminated by newline (@code{'\n'}), EOF, or EOL characters.  No
input can be read until an entire line has been typed by the user, and
the @code{read} function (@pxref{I/O Primitives}) returns at most a
single line of input, no matter how many bytes are requested.

In canonical input mode, the operating system provides input editing
facilities: some characters are interpreted specially to perform editing
operations within the current line of text, such as ERASE and KILL.
@xref{Editing Characters}.

The constants @code{_POSIX_MAX_CANON} and @code{MAX_CANON} parameterize
the maximum number of bytes which may appear in a single line of
canonical input.  @xref{Limits for Files}.  You are guaranteed a maximum
line length of at least @code{MAX_CANON} bytes, but the maximum might be
larger, and might even dynamically change size.

@cindex noncanonical input processing
In @dfn{noncanonical input processing} mode, characters are not grouped
into lines, and ERASE and KILL processing is not performed.  The
granularity with which bytes are read in noncanonical input mode is
controlled by the MIN and TIME settings.  @xref{Noncanonical Input}.

Most programs use canonical input mode, because this gives the user a
way to edit input line by line.  The usual reason to use noncanonical
mode is when the program accepts single-character commands or provides
its own editing facilities.

The choice of canonical or noncanonical input is controlled by the
@code{ICANON} flag in the @code{c_lflag} member of @code{struct termios}.
@xref{Local Modes}.

@node Terminal Modes
@section Terminal Modes

@pindex termios.h
This section describes the various terminal attributes that control how
input and output are done.  The functions, data structures, and symbolic
constants are all declared in the header file @file{termios.h}.
@c !!! should mention terminal attributes are distinct from file attributes

@menu
* Mode Data Types::             The data type @code{struct termios} and
                                 related types. 
* Mode Functions::              Functions to read and set the terminal
                                 attributes. 
* Setting Modes::               The right way to set terminal attributes
                                 reliably.
* Input Modes::                 Flags controlling low-level input handling.
* Output Modes::                Flags controlling low-level output handling.
* Control Modes::               Flags controlling serial port behavior.
* Local Modes::                 Flags controlling high-level input handling.
* Line Speed::                  How to read and set the terminal line speed.
* Special Characters::          Characters that have special effects,
			         and how to change them.
* Noncanonical Input::          Controlling how long to wait for input.
@end menu

@node Mode Data Types
@subsection Terminal Mode Data Types
@cindex terminal mode data types

The entire collection of attributes of a terminal is stored in a
structure of type @code{struct termios}.  This structure is used
with the functions @code{tcgetattr} and @code{tcsetattr} to read
and set the attributes.

@comment termios.h
@comment POSIX.1
@deftp {Data Type} {struct termios}
Structure that records all the I/O attributes of a terminal.  The
structure includes at least the following members:

@table @code
@item tcflag_t c_iflag
A bit mask specifying flags for input modes; see @ref{Input Modes}.

@item tcflag_t c_oflag
A bit mask specifying flags for output modes; see @ref{Output Modes}.

@item tcflag_t c_cflag
A bit mask specifying flags for control modes; see @ref{Control Modes}.

@item tcflag_t c_lflag
A bit mask specifying flags for local modes; see @ref{Local Modes}.

@item cc_t c_cc[NCCS]
An array specifying which characters are associated with various
control functions; see @ref{Special Characters}.
@end table

The @code{struct termios} structure also contains members which
encode input and output transmission speeds, but the representation is
not specified.  @xref{Line Speed}, for how to examine and store the
speed values.
@end deftp

The following sections describe the details of the members of the
@code{struct termios} structure.

@comment termios.h
@comment POSIX.1
@deftp {Data Type} tcflag_t
This is an unsigned integer type used to represent the various
bit masks for terminal flags.
@end deftp

@comment termios.h
@comment POSIX.1
@deftp {Data Type} cc_t
This is an unsigned integer type used to represent characters associated
with various terminal control functions.
@end deftp

@comment termios.h
@comment POSIX.1
@deftypevr Macro int NCCS
The value of this macro is the number of elements in the @code{c_cc}
array.
@end deftypevr

@node Mode Functions
@subsection Terminal Mode Functions
@cindex terminal mode functions

@comment termios.h
@comment POSIX.1
@deftypefun int tcgetattr (int @var{filedes}, struct termios *@var{termios-p})
This function is used to examine the attributes of the terminal
device with file descriptor @var{filedes}.  The attributes are returned
in the structure that @var{termios-p} points to.

If successful, @code{tcgetattr} returns @code{0}.  A return value of @code{-1}
indicates an error.  The following @code{errno} error conditions are
defined for this function:

@table @code
@item EBADF
The @var{filedes} argument is not a valid file descriptor.

@item ENOTTY
The @var{filedes} is not associated with a terminal.
@end table
@end deftypefun

@comment termios.h
@comment POSIX.1
@deftypefun int tcsetattr (int @var{filedes}, int @var{when}, const struct termios *@var{termios-p})
This function sets the attributes of the terminal device with file
descriptor @var{filedes}.  The new attributes are taken from the
structure that @var{termios-p} points to.

The @var{when} argument specifies how to deal with input and output
already queued.  It can be one of the following values:

@table @code
@comment termios.h
@comment POSIX.1
@item TCSANOW
@vindex TCSANOW
Make the change immediately.

@comment termios.h
@comment POSIX.1
@item TCSADRAIN
@vindex TCSADRAIN
Make the change after waiting until all queued output has been written.
You should usually use this option when changing parameters that affect
output.

@comment termios.h
@comment POSIX.1
@item TCSAFLUSH
@vindex TCSAFLUSH
This is like @code{TCSADRAIN}, but also discards any queued input.

@comment termios.h
@comment BSD
@item TCSASOFT
@vindex TCSASOFT
This is a flag bit that you can add to any of the above alternatives.
Its meaning is to inhibit alteration of the state of the terminal
hardware.  It is a BSD extension; it is only supported on BSD systems
and the GNU system.

Using @code{TCSASOFT} is exactly the same as setting the @code{CIGNORE}
bit in the @code{c_cflag} member of the structure @var{termios-p} points
to.  @xref{Control Modes}, for a description of @code{CIGNORE}.
@end table

If this function is called from a background process on its controlling
terminal, normally all processes in the process group are sent a
@code{SIGTTOU} signal, in the same way as if the process were trying to
write to the terminal.  The exception is if the calling process itself
is ignoring or blocking @code{SIGTTOU} signals, in which case the
operation is performed and no signal is sent.  @xref{Job Control}.

If successful, @code{tcsetattr} returns @code{0}.  A return value of
@code{-1} indicates an error.  The following @code{errno} error
conditions are defined for this function:

@table @code
@item EBADF
The @var{filedes} argument is not a valid file descriptor.

@item ENOTTY
The @var{filedes} is not associated with a terminal.

@item EINVAL
Either the value of the @code{when} argument is not valid, or there is
something wrong with the data in the @var{termios-p} argument.
@end table
@end deftypefun

Although @code{tcgetattr} and @code{tcsetattr} specify the terminal
device with a file descriptor, the attributes are those of the terminal
device itself and not of the file descriptor.  This means that the
effects of changing terminal attributes are persistent; if another
process opens the terminal file later on, it will see the changed
attributes even though it doesn't have anything to do with the open file
descriptor you originally specified in changing the attributes.

Similarly, if a single process has multiple or duplicated file
descriptors for the same terminal device, changing the terminal
attributes affects input and output to all of these file
descriptors.  This means, for example, that you can't open one file
descriptor or stream to read from a terminal in the normal
line-buffered, echoed mode; and simultaneously have another file
descriptor for the same terminal that you use to read from it in
single-character, non-echoed mode.  Instead, you have to explicitly
switch the terminal back and forth between the two modes.

@node Setting Modes
@subsection Setting Terminal Modes Properly

When you set terminal modes, you should call @code{tcgetattr} first to
get the current modes of the particular terminal device, modify only
those modes that you are really interested in, and store the result with
@code{tcsetattr}.

It's a bad idea to simply initialize a @code{struct termios} structure
to a chosen set of attributes and pass it directly to @code{tcsetattr}.
Your program may be run years from now, on systems that support members
not documented in this manual.  The way to avoid setting these members
to unreasonable values is to avoid changing them.

What's more, different terminal devices may require different mode
settings in order to function properly.  So you should avoid blindly
copying attributes from one terminal device to another.