terminal.texi

一个C源代码分析器

significance of the next character the user types.  Even if the
character would normally perform some editting function or generate a
signal, it is read as a plain character.  This is the analogue of the
@kbd{C-q} command in Emacs.  ``LNEXT'' stands for ``literal next.''

The LNEXT character is usually @kbd{C-v}.
@end deftypevr

@comment termios.h
@comment BSD
@deftypevr Macro int VDISCARD
@cindex DISCARD character
This is the subscript for the DISCARD character in the special control
character array.  @code{@var{termios}.c_cc[VDISCARD]} holds the character
itself.

The DISCARD character is recognized only when @code{IEXTEN} is set, but
in both canonical and noncanonical mode.  Its effect is to toggle the
discard-output flag.  When this flag is set, all program output is
discarded.  Setting the flag also discards all output currently in the
output buffer.  Typing any other character resets the flag.
@end deftypevr

@comment termios.h
@comment BSD
@deftypevr Macro int VSTATUS
@cindex STATUS character
This is the subscript for the STATUS character in the special control
character array.  @code{@var{termios}.c_cc[VSTATUS]} holds the character
itself.

The STATUS character's effect is to print out a status message about how
the current process is running.

The STATUS character is recognized only in canonical mode, and only if
@code{NOKERNINFO} is not set.
@end deftypevr

@node Noncanonical Input
@subsection Noncanonical Input

In noncanonical input mode, the special editing characters such as
ERASE and KILL are ignored.  The system facilities for the user to edit
input are disabled in noncanonical mode, so that all input characters
(unless they are special for signal or flow-control purposes) are passed
to the application program exactly as typed.  It is up to the
application program to give the user ways to edit the input, if
appropriate.

Noncanonical mode offers special parameters called MIN and TIME for
controlling whether and how long to wait for input to be available.  You
can even use them to avoid ever waiting---to return immediately with
whatever input is available, or with no input.

The MIN and TIME are stored in elements of the @code{c_cc} array, which
is a member of the @w{@code{struct termios}} structure.  Each element of
this array has a particular role, and each element has a symbolic
constant that stands for the index of that element.  @code{VMIN} and
@code{VMAX} are the names for the indices in the array of the MIN and
TIME slots.

@comment termios.h
@comment POSIX.1
@deftypevr Macro int VMIN
@cindex MIN termios slot
This is the subscript for the MIN slot in the @code{c_cc} array.  Thus,
@code{@var{termios}.c_cc[VMIN]} is the value itself.

The MIN slot is only meaningful in noncanonical input mode; it
specifies the minimum number of bytes that must be available in the
input queue in order for @code{read} to return.
@end deftypevr

@comment termios.h
@comment POSIX.1
@deftypevr Macro int VTIME
@cindex TIME termios slot
This is the subscript for the TIME slot in the @code{c_cc} array.  Thus,
@code{@var{termios}.c_cc[VTIME]} is the value itself.

The TIME slot is only meaningful in noncanonical input mode; it
specifies how long to wait for input before returning, in units of 0.1
seconds.
@end deftypevr

The MIN and TIME values interact to determine the criterion for when
@code{read} should return; their precise meanings depend on which of
them are nonzero.  There are four possible cases:

@itemize @bullet
@item
Both TIME and MIN are nonzero.

In this case, TIME specifies how long to wait after each input character
to see if more input arrives.  After the first character received,
@code{read} keeps waiting until either MIN bytes have arrived in all, or
TIME elapses with no further input.

@code{read} always blocks until the first character arrives, even if
TIME elapses first.  @code{read} can return more than MIN characters if
more than MIN happen to be in the queue.

@item 
Both MIN and TIME are zero.

In this case, @code{read} always returns immediately with as many
characters as are available in the queue, up to the number requested.
If no input is immediately available, @code{read} returns a value of
zero.

@item
MIN is zero but TIME has a nonzero value.

In this case, @code{read} waits for time TIME for input to become
available; the availability of a single byte is enough to satisfy the
read request and cause @code{read} to return.  When it returns, it
returns as many characters as are available, up to the number requested.
If no input is available before the timer expires, @code{read} returns a
value of zero.

@item
TIME is zero but MIN has a nonzero value.

In this case, @code{read} waits until at least MIN bytes are available
in the queue.  At that time, @code{read} returns as many characters as
are available, up to the number requested.  @code{read} can return more
than MIN characters if more than MIN happen to be in the queue.
@end itemize

What happens if MIN is 50 and you ask to read just 10 bytes?
Normally, @code{read} waits until there are 50 bytes in the buffer (or,
more generally, the wait condition described above is satisfied), and
then reads 10 of them, leaving the other 40 buffered in the operating
system for a subsequent call to @code{read}.

@strong{Portability note:} On some systems, the MIN and TIME slots are
actually the same as the EOF and EOL slots.  This causes no serious
problem because the MIN and TIME slots are used only in noncanonical
input and the EOF and EOL slots are used only in canonical input, but it
isn't very clean.  The GNU library allocates separate slots for these
uses.

@comment termios.h
@comment BSD
@deftypefun int cfmakeraw (struct termios *@var{termios-p})
This function provides an easy way to set up @code{*@var{termios-p}} for
what has traditionally been called ``raw mode'' in BSD.  This uses
noncanonical input, and turns off most processing to give an unmodified
channel to the terminal.

It does exactly this:
@smallexample
  @var{termios-p}->c_iflag &= ~(IGNBRK|BRKINT|PARMRK|ISTRIP
                                |INLCR|IGNCR|ICRNL|IXON);
  @var{termios-p}->c_oflag &= ~OPOST;
  @var{termios-p}->c_lflag &= ~(ECHO|ECHONL|ICANON|ISIG|IEXTEN);
  @var{termios-p}->c_cflag &= ~(CSIZE|PARENB);
  @var{termios-p}->c_cflag |= CS8;
@end smallexample
@end deftypefun

@node Line Control
@section Line Control Functions
@cindex terminal line control functions

These functions perform miscellaneous control actions on terminal
devices.  As regards terminal access, they are treated like doing
output: if any of these functions is used by a background process on its
controlling terminal, normally all processes in the process group are
sent a @code{SIGTTOU} signal.  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}.

@cindex break condition, generating
@comment termios.h
@comment POSIX.1
@deftypefun int tcsendbreak (int @var{filedes}, int @var{duration})
This function generates a break condition by transmitting a stream of
zero bits on the terminal associated with the file descriptor
@var{filedes}.  The duration of the break is controlled by the
@var{duration} argument.  If zero, the duration is between 0.25 and 0.5
seconds.  The meaning of a nonzero value depends on the operating system.

This function does nothing if the terminal is not an asynchronous serial
data port.

The return value is normally zero.  In the event of an error, a value
of @code{-1} is returned.  The following @code{errno} error conditions
are defined for this function:

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

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


@cindex flushing terminal output queue
@cindex terminal output queue, flushing
@comment termios.h
@comment POSIX.1
@deftypefun int tcdrain (int @var{filedes})
The @code{tcdrain} function waits until all queued
output to the terminal @var{filedes} has been transmitted.

The return value is normally zero.  In the event of an error, a value
of @code{-1} is returned.  The following @code{errno} error conditions
are defined for this function:

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

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

@item EINTR
The operation was interrupted by delivery of a signal.
@xref{Interrupted Primitives}.
@end table
@end deftypefun


@cindex clearing terminal input queue
@cindex terminal input queue, clearing
@comment termios.h
@comment POSIX.1
@deftypefun int tcflush (int @var{filedes}, int @var{queue})
The @code{tcflush} function is used to clear the input and/or output
queues associated with the terminal file @var{filedes}.  The @var{queue}
argument specifies which queue(s) to clear, and can be one of the
following values:

@c Extra blank lines here make it look better.
@table @code
@vindex TCIFLUSH
@item TCIFLUSH

Clear any input data received, but not yet read.

@vindex TCOFLUSH
@item TCOFLUSH

Clear any output data written, but not yet transmitted.

@vindex TCIOFLUSH
@item TCIOFLUSH

Clear both queued input and output.
@end table

The return value is normally zero.  In the event of an error, a value
of @code{-1} is returned.  The following @code{errno} error conditions
are defined for this function:

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

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

@item EINVAL
A bad value was supplied as the @var{queue} argument.
@end table

It is unfortunate that this function is named @code{tcflush}, because
the term ``flush'' is normally used for quite another operation---waiting
until all output is transmitted---and using it for discarding input or
output would be confusing.  Unfortunately, the name @code{tcflush} comes
from POSIX and we cannot change it.
@end deftypefun

@cindex flow control, terminal
@cindex terminal flow control
@comment termios.h
@comment POSIX.1
@deftypefun int tcflow (int @var{filedes}, int @var{action})
The @code{tcflow} function is used to perform operations relating to
XON/XOFF flow control on the terminal file specified by @var{filedes}.

The @var{action} argument specifies what operation to perform, and can
be one of the following values:

@table @code
@vindex TCOOFF
@item TCOOFF
Suspend transmission of output.

@vindex TCOON
@item TCOON
Restart transmission of output.

@vindex TCIOFF
@item TCIOFF
Transmit a STOP character.

@vindex TCION
@item TCION
Transmit a START character.
@end table

For more information about the STOP and START characters, see @ref{Special
Characters}.

The return value is normally zero.  In the event of an error, a value
of @code{-1} is returned.  The following @code{errno} error conditions
are defined for this function:

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

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

@vindex EINVAL
@item EINVAL
A bad value was supplied as the @var{action} argument.
@end table
@end deftypefun

@node Noncanon Example
@section Noncanonical Mode Example

Here is an example program that shows how you can set up a terminal
device to read single characters in noncanonical input mode, without
echo.

@smallexample
@include termios.c.texi
@end smallexample

This program is careful to restore the original terminal modes before
exiting or terminating with a signal.  It uses the @code{atexit}
function (@pxref{Cleanups on Exit}) to make sure this is done
by @code{exit}.

@ignore
@c !!!! the example doesn't handle any signals!
The signals handled in the example are the ones that typically occur due
to actions of the user.  It might be desirable to handle other signals
such as SIGSEGV that can result from bugs in the program.
@end ignore

The shell is supposed to take care of resetting the terminal modes when
a process is stopped or continued; see @ref{Job Control}.  But some
existing shells do not actually do this, so you may wish to establish
handlers for job control signals that reset terminal modes.  The above
example does so.