library_16.html

Linux程序员的工作手册

<!-- This HTML file has been created by texi2html 1.27
     from library.texinfo on 3 March 1994 -->

<TITLE>The GNU C Library - Low-Level Terminal Interface</TITLE>
<P>Go to the <A HREF="library_15.html" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_15.html">previous</A>, <A HREF="library_17.html" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_17.html">next</A> section.<P>
<H1><A NAME="SEC268" HREF="library_toc.html#SEC268" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC268">Low-Level Terminal Interface</A></H1>
<P>
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.
<P>
Most of the functions in this chapter operate on file descriptors.
See section <A HREF="library_12.html#SEC171" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_12.html#SEC171">Low-Level Input/Output</A>, for more information about what a file
descriptor is and how to open a file descriptor for a terminal device.
<P>
<A NAME="IDX1080"></A>
<A NAME="IDX1081"></A>
<H2><A NAME="SEC269" HREF="library_toc.html#SEC269" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC269">Identifying Terminals</A></H2>
<P>
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</CODE>
function.
<A NAME="IDX1082"></A>
<P>
Prototypes for both <CODE>isatty</CODE> and <CODE>ttyname</CODE> are declared in
the header file <TT>`unistd.h'</TT>.
<P>
<A NAME="IDX1083"></A>
<U>Function:</U> int <B>isatty</B> <I>(int <VAR>filedes</VAR>)</I><P>
This function returns <CODE>1</CODE> if <VAR>filedes</VAR> is a file descriptor
associated with an open terminal device, and <CODE>0</CODE> otherwise.
<P>
If a file descriptor is associated with a terminal, you can get its
associated file name using the <CODE>ttyname</CODE> function.  See also the
<CODE>ctermid</CODE> function, described in section <A HREF="library_24.html#SEC426" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_24.html#SEC426">Identifying the Controlling Terminal</A>.
<P>
<A NAME="IDX1084"></A>
<U>Function:</U> char * <B>ttyname</B> <I>(int <VAR>filedes</VAR>)</I><P>
If the file descriptor <VAR>filedes</VAR> is associated with a terminal
device, the <CODE>ttyname</CODE> 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.
<P>
<H2><A NAME="SEC270" HREF="library_toc.html#SEC270" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC270">I/O Queues</A></H2>
<P>
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 <EM>within the kernel</EM> independent of the buffering
implemented by I/O streams (see section <A HREF="library_11.html#SEC117" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_11.html#SEC117">Input/Output on Streams</A>).
<A NAME="IDX1085"></A>
<A NAME="IDX1086"></A>
<P>
The <DFN>terminal input queue</DFN> is also sometimes referred to as its
<DFN>typeahead buffer</DFN>.  It holds the characters that have been received
from the terminal but not yet read by any process.
<P>
The size of the terminal's input queue is described by the
<CODE>_POSIX_MAX_INPUT</CODE> and <CODE>MAX_INPUT</CODE> parameters; see section <A HREF="library_27.html#SEC463" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_27.html#SEC463">Limits on File System Capacity</A>.  If input flow control is enabled by setting the
<CODE>IXOFF</CODE> input mode bit (see section <A HREF="library_16.html#SEC276" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_16.html#SEC276">Input Modes</A>), 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.  (This is unlikely if you are
typing the input by hand!)
<A NAME="IDX1087"></A>
<P>
The <DFN>terminal output queue</DFN> 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</CODE> input mode bit (see section <A HREF="library_16.html#SEC276" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_16.html#SEC276">Input Modes</A>), the
terminal driver obeys STOP and STOP characters sent by the terminal to
stop and restart transmission of output.
<P>
<DFN>Clearing</DFN> 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.
<P>
<H2><A NAME="SEC271" HREF="library_toc.html#SEC271" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC271">Two Styles of Input: Canonical or Not</A></H2>
<P>
POSIX systems support two basic modes of input: canonical and
noncanonical.
<A NAME="IDX1088"></A>
<P>
In <DFN>canonical input processing</DFN> mode, terminal input is processed in
lines terminated by newline (<CODE>'\n'</CODE>), EOF, or EOL characters.  No
input can be read until an entire line has been typed by the user, and
the <CODE>read</CODE> function (see section <A HREF="library_12.html#SEC173" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_12.html#SEC173">Input and Output Primitives</A>) returns at most a
single line of input, no matter how many bytes are requested.
<P>
In canonical input mode, the operating system provides input editing
facilities: the ERASE and KILL characters are interpreted specially to
perform editing operations within the current line of text.
See section <A HREF="library_16.html#SEC282" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_16.html#SEC282">Characters for Input Editing</A>.
<P>
The constants <CODE>_POSIX_MAX_CANON</CODE> and <CODE>MAX_CANON</CODE> parameterize
the maximum number of bytes which may appear in a single line of
canonical input.  See section <A HREF="library_27.html#SEC463" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_27.html#SEC463">Limits on File System Capacity</A>.
<A NAME="IDX1089"></A>
<P>
In <DFN>noncanonical input processing</DFN> 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.  See section <A HREF="library_16.html#SEC287" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_16.html#SEC287">Noncanonical Input</A>.
<P>
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.
<P>
The choice of canonical or noncanonical input is controlled by the
<CODE>ICANON</CODE> flag in the <CODE>c_lflag</CODE> member of <CODE>struct termios</CODE>.
See section <A HREF="library_16.html#SEC279" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_16.html#SEC279">Local Modes</A>.
<P>
<H2><A NAME="SEC272" HREF="library_toc.html#SEC272" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC272">Terminal Modes</A></H2>
<A NAME="IDX1090"></A>
<P>
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 <TT>`termios.h'</TT>.
<P>
<A NAME="IDX1091"></A>
<H3><A NAME="SEC273" HREF="library_toc.html#SEC273" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC273">Terminal Mode Data Types</A></H3>
<P>
The entire collection of attributes of a terminal is stored in a
structure of type <CODE>struct termios</CODE>.  This structure is used
with the functions <CODE>tcgetattr</CODE> and <CODE>tcsetattr</CODE> to read
and set the attributes.
<P>
<A NAME="IDX1092"></A>
<U>Data Type:</U> <B>struct termios</B><P>
Structure that records all the I/O attributes of a terminal.  The
structure includes at least the following members:
<P>
<DL COMPACT>
<DT><CODE>tcflag_t c_iflag</CODE>
<DD>A bit mask specifying input modes; see section <A HREF="library_16.html#SEC276" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_16.html#SEC276">Input Modes</A>.
<P>
<DT><CODE>tcflag_t c_oflag</CODE>
<DD>A bit mask specifying output modes; see section <A HREF="library_16.html#SEC277" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_16.html#SEC277">Output Modes</A>.
<P>
<DT><CODE>tcflag_t c_cflag</CODE>
<DD>A bit mask specifying control modes; see section <A HREF="library_16.html#SEC278" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_16.html#SEC278">Control Modes</A>.
<P>
<DT><CODE>tcflag_t c_lflag</CODE>
<DD>A bit mask specifying flags for local modes; see section <A HREF="library_16.html#SEC279" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_16.html#SEC279">Local Modes</A>.
<P>
<DT><CODE>cc_t c_cc[NCCS]</CODE>
<DD>An array specifying which characters are associated with various
control functions; see section <A HREF="library_16.html#SEC281" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_16.html#SEC281">Special Characters</A>.
</DL>
<P>
The <CODE>struct termios</CODE> structure also contains members which
encode input and output transmission speeds, but the representation is
not specified.  See section <A HREF="library_16.html#SEC280" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_16.html#SEC280">Line Speed</A>, for how to examine and store the
speed values.
<P>
The following sections describe the details of the members of the
<CODE>struct termios</CODE> structure.
<P>
<A NAME="IDX1093"></A>
<U>Data Type:</U> <B>tcflag_t</B><P>
This is an unsigned integer type used to represent the various
bit masks for terminal flags.
<P>
<A NAME="IDX1094"></A>
<U>Data Type:</U> <B>cc_t</B><P>
This is an unsigned integer type used to represent characters associated
with various terminal control functions.
<P>
<A NAME="IDX1095"></A>
<U>Macro:</U> int <B>NCCS</B><P>
The value of this macro is the number of elements in the <CODE>c_cc</CODE>
array.
<P>
<A NAME="IDX1096"></A>
<H3><A NAME="SEC274" HREF="library_toc.html#SEC274" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC274">Terminal Mode Functions</A></H3>
<P>
<A NAME="IDX1097"></A>
<U>Function:</U> int <B>tcgetattr</B> <I>(int <VAR>filedes</VAR>, struct termios *<VAR>termios_p</VAR>)</I><P>
This function is used to examine the attributes of the terminal
device with file descriptor <VAR>filedes</VAR>.  The attributes are returned
in the structure that <VAR>termios_p</VAR> points to.
<P>
If successful, <CODE>tcgetattr</CODE> returns <CODE>0</CODE>.  A return value of <CODE>-1</CODE>
indicates an error.  The following <CODE>errno</CODE> error conditions are
defined for this function:
<P>
<DL COMPACT>
<DT><CODE>EBADF</CODE>
<DD>The <VAR>filedes</VAR> argument is not a valid file descriptor.
<P>
<DT><CODE>ENOTTY</CODE>
<DD>The <VAR>filedes</VAR> is not associated with a terminal.
</DL>
<P>
<A NAME="IDX1098"></A>
<U>Function:</U> int <B>tcsetattr</B> <I>(int <VAR>filedes</VAR>, int <VAR>when</VAR>, const struct termios *<VAR>termios_p</VAR>)</I><P>
This function sets the attributes of the terminal device with file
descriptor <VAR>filedes</VAR>.  The new attributes are taken from the
structure that <VAR>termios_p</VAR> points to.
<P>
The <VAR>when</VAR> argument specifies how to deal with input and output
already queued.  It can be one of the following values:
<P>
<DL COMPACT>
<A NAME="IDX1099"></A>
<DT><CODE>TCSANOW</CODE>
<DD>Make the change immediately.
<P>
<A NAME="IDX1100"></A>
<DT><CODE>TCSADRAIN</CODE>
<DD>Make the change after waiting until all queued output has been written.
You should usually use this option when changing parameters that affect
output.
<P>
<A NAME="IDX1101"></A>
<DT><CODE>TCSAFLUSH</CODE>
<DD>This is like <CODE>TCSADRAIN</CODE>, but also discards any queued input.
<P>
<A NAME="IDX1102"></A>
<DT><CODE>TCSASOFT</CODE>
<DD>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 has no effect on non-BSD systems.
</DL>
<P>
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</CODE> 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</CODE> signals, in which case the
operation is performed and no signal is sent.  See section <A HREF="library_24.html#SEC411" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_24.html#SEC411">Job Control</A>.
<P>
If successful, <CODE>tcsetattr</CODE> returns <CODE>0</CODE>.  A return value of
<CODE>-1</CODE> indicates an error.  The following <CODE>errno</CODE> error
conditions are defined for this function:
<P>
<DL COMPACT>
<DT><CODE>EBADF</CODE>
<DD>The <VAR>filedes</VAR> argument is not a valid file descriptor.
<P>
<DT><CODE>ENOTTY</CODE>
<DD>The <VAR>filedes</VAR> is not associated with a terminal.
<P>
<DT><CODE>EINVAL</CODE>
<DD>Either the value of the <CODE>when</CODE> argument is not valid, or there is
something wrong with the data in the <VAR>termios_p</VAR> argument.
</DL>
<P>
Although <CODE>tcgetattr</CODE> and <CODE>tcsetattr</CODE> 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.
<P>
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