e52236e536
2000-04-30 Ulrich Drepper <drepper@redhat.com> * manual/string.texi: Fix typo. * manual/terminal.texi: Document gtty and stty. Patch by Bryan Henderson <bryanh@giraffe-data.com>.
2127 lines
75 KiB
Plaintext
2127 lines
75 KiB
Plaintext
@node Low-Level Terminal Interface, Syslog, Sockets, Top
|
|
@c %MENU% How to change the characteristics of a terminal device
|
|
@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. Posix.
|
|
* BSD Terminal Modes:: BSD compatible terminal mode setting
|
|
* Line Control:: Sending break sequences, clearing
|
|
terminal buffers @dots{}
|
|
* Noncanon Example:: How to read single characters without echo.
|
|
* Pseudo-Terminals:: How to open a pseudo-terminal.
|
|
@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 the functions in this section 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 @math{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
|
|
|
|
@comment unistd.h
|
|
@comment POSIX.1
|
|
@deftypefun int ttyname_r (int @var{filedes}, char *@var{buf}, size_t @var{len})
|
|
The @code{ttyname_r} function is similar to the @code{ttyname} function
|
|
except that it places its result into the user-specified buffer starting
|
|
at @var{buf} with length @var{len}.
|
|
|
|
The normal return value from @code{ttyname_r} is @math{0}. Otherwise an
|
|
error number is returned to indicate the 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 ERANGE
|
|
The buffer length @var{len} is too small to store the string to be
|
|
returned.
|
|
@end table
|
|
@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 input queue is described by the @code{MAX_INPUT} and
|
|
@w{@code{_POSIX_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 START 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}.
|
|
|
|
Don't confuse terminal attributes with file attributes. A device special
|
|
file which is associated with a terminal has file attributes as described
|
|
in @ref{File Attributes}. These are unrelated to the attributes of the
|
|
terminal device itself, which are discussed in this section.
|
|
|
|
@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 @math{0}. A return value of @math{-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 @math{0}. A return value of
|
|
@math{-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.
|
|
|
|
When a member contains a collection of independent flags, as the
|
|
@code{c_iflag}, @code{c_oflag} and @code{c_cflag} members do, even
|
|
setting the entire member is a bad idea, because particular operating
|
|
systems have their own flags. Instead, you should start with the
|
|
current value of the member and alter only the flags whose values matter
|
|
in your program, leaving any other flags unchanged.
|
|
|
|
Here is an example of how to set one flag (@code{ISTRIP}) in the
|
|
@code{struct termios} structure while properly preserving all the other
|
|
data in the structure:
|
|
|
|
@smallexample
|
|
@group
|
|
int
|
|
set_istrip (int desc, int value)
|
|
@{
|
|
struct termios settings;
|
|
int result;
|
|
@end group
|
|
|
|
@group
|
|
result = tcgetattr (desc, &settings);
|
|
if (result < 0)
|
|
@{
|
|
perror ("error in tcgetattr");
|
|
return 0;
|
|
@}
|
|
@end group
|
|
@group
|
|
settings.c_iflag &= ~ISTRIP;
|
|
if (value)
|
|
settings.c_iflag |= ISTRIP;
|
|
@end group
|
|
@group
|
|
result = tcsetattr (desc, TCSANOW, &settings);
|
|
if (result < 0)
|
|
@{
|
|
perror ("error in tcgetattr");
|
|
return;
|
|
@}
|
|
return 1;
|
|
@}
|
|
@end group
|
|
@end smallexample
|
|
|
|
@node Input Modes
|
|
@subsection Input Modes
|
|
|
|
This section describes the terminal attribute flags that control
|
|
fairly low-level aspects of input processing: handling of parity errors,
|
|
break signals, flow control, and @key{RET} and @key{LFD} characters.
|
|
|
|
All of these flags are bits in the @code{c_iflag} member of the
|
|
@code{struct termios} structure. The member is an integer, and you
|
|
change flags using the operators @code{&}, @code{|} and @code{^}. Don't
|
|
try to specify the entire value for @code{c_iflag}---instead, change
|
|
only specific flags and leave the rest untouched (@pxref{Setting
|
|
Modes}).
|
|
|
|
@comment termios.h
|
|
@comment POSIX.1
|
|
@deftypevr Macro tcflag_t INPCK
|
|
@cindex parity checking
|
|
If this bit is set, input parity checking is enabled. If it is not set,
|
|
no checking at all is done for parity errors on input; the
|
|
characters are simply passed through to the application.
|
|
|
|
Parity checking on input processing is independent of whether parity
|
|
detection and generation on the underlying terminal hardware is enabled;
|
|
see @ref{Control Modes}. For example, you could clear the @code{INPCK}
|
|
input mode flag and set the @code{PARENB} control mode flag to ignore
|
|
parity errors on input, but still generate parity on output.
|
|
|
|
If this bit is set, what happens when a parity error is detected depends
|
|
on whether the @code{IGNPAR} or @code{PARMRK} bits are set. If neither
|
|
of these bits are set, a byte with a parity error is passed to the
|
|
application as a @code{'\0'} character.
|
|
@end deftypevr
|
|
|
|
@comment termios.h
|
|
@comment POSIX.1
|
|
@deftypevr Macro tcflag_t IGNPAR
|
|
If this bit is set, any byte with a framing or parity error is ignored.
|
|
This is only useful if @code{INPCK} is also set.
|
|
@end deftypevr
|
|
|
|
@comment termios.h
|
|
@comment POSIX.1
|
|
@deftypevr Macro tcflag_t PARMRK
|
|
If this bit is set, input bytes with parity or framing errors are marked
|
|
when passed to the program. This bit is meaningful only when
|
|
@code{INPCK} is set and @code{IGNPAR} is not set.
|
|
|
|
The way erroneous bytes are marked is with two preceding bytes,
|
|
@code{377} and @code{0}. Thus, the program actually reads three bytes
|
|
for one erroneous byte received from the terminal.
|
|
|
|
If a valid byte has the value @code{0377}, and @code{ISTRIP} (see below)
|
|
is not set, the program might confuse it with the prefix that marks a
|
|
parity error. So a valid byte @code{0377} is passed to the program as
|
|
two bytes, @code{0377} @code{0377}, in this case.
|
|
@end deftypevr
|
|
|
|
@comment termios.h
|
|
@comment POSIX.1
|
|
@deftypevr Macro tcflag_t ISTRIP
|
|
If this bit is set, valid input bytes are stripped to seven bits;
|
|
otherwise, all eight bits are available for programs to read.
|
|
@end deftypevr
|
|
|
|
@comment termios.h
|
|
@comment POSIX.1
|
|
@deftypevr Macro tcflag_t IGNBRK
|
|
If this bit is set, break conditions are ignored.
|
|
|
|
@cindex break condition, detecting
|
|
A @dfn{break condition} is defined in the context of asynchronous
|
|
serial data transmission as a series of zero-value bits longer than a
|
|
single byte.
|
|
@end deftypevr
|
|
|
|
@comment termios.h
|
|
@comment POSIX.1
|
|
@deftypevr Macro tcflag_t BRKINT
|
|
If this bit is set and @code{IGNBRK} is not set, a break condition
|
|
clears the terminal input and output queues and raises a @code{SIGINT}
|
|
signal for the foreground process group associated with the terminal.
|
|
|
|
If neither @code{BRKINT} nor @code{IGNBRK} are set, a break condition is
|
|
passed to the application as a single @code{'\0'} character if
|
|
@code{PARMRK} is not set, or otherwise as a three-character sequence
|
|
@code{'\377'}, @code{'\0'}, @code{'\0'}.
|
|
@end deftypevr
|
|
|
|
@comment termios.h
|
|
@comment POSIX.1
|
|
@deftypevr Macro tcflag_t IGNCR
|
|
If this bit is set, carriage return characters (@code{'\r'}) are
|
|
discarded on input. Discarding carriage return may be useful on
|
|
terminals that send both carriage return and linefeed when you type the
|
|
@key{RET} key.
|
|
@end deftypevr
|
|
|
|
@comment termios.h
|
|
@comment POSIX.1
|
|
@deftypevr Macro tcflag_t ICRNL
|
|
If this bit is set and @code{IGNCR} is not set, carriage return characters
|
|
(@code{'\r'}) received as input are passed to the application as newline
|
|
characters (@code{'\n'}).
|
|
@end deftypevr
|
|
|
|
@comment termios.h
|
|
@comment POSIX.1
|
|
@deftypevr Macro tcflag_t INLCR
|
|
If this bit is set, newline characters (@code{'\n'}) received as input
|
|
are passed to the application as carriage return characters (@code{'\r'}).
|
|
@end deftypevr
|
|
|
|
@comment termios.h
|
|
@comment POSIX.1
|
|
@deftypevr Macro tcflag_t IXOFF
|
|
If this bit is set, start/stop control on input is enabled. In other
|
|
words, the computer sends STOP and START characters as necessary to
|
|
prevent input from coming in faster than programs are reading it. The
|
|
idea is that the actual terminal hardware that is generating the input
|
|
data responds to a STOP character by suspending transmission, and to a
|
|
START character by resuming transmission. @xref{Start/Stop Characters}.
|
|
@end deftypevr
|
|
|
|
@comment termios.h
|
|
@comment POSIX.1
|
|
@deftypevr Macro tcflag_t IXON
|
|
If this bit is set, start/stop control on output is enabled. In other
|
|
words, if the computer receives a STOP character, it suspends output
|
|
until a START character is received. In this case, the STOP and START
|
|
characters are never passed to the application program. If this bit is
|
|
not set, then START and STOP can be read as ordinary characters.
|
|
@xref{Start/Stop Characters}.
|
|
@c !!! mention this interferes with using C-s and C-q for programs like emacs
|
|
@end deftypevr
|
|
|
|
@comment termios.h
|
|
@comment BSD
|
|
@deftypevr Macro tcflag_t IXANY
|
|
If this bit is set, any input character restarts output when output has
|
|
been suspended with the STOP character. Otherwise, only the START
|
|
character restarts output.
|
|
|
|
This is a BSD extension; it exists only on BSD systems and the GNU system.
|
|
@end deftypevr
|
|
|
|
@comment termios.h
|
|
@comment BSD
|
|
@deftypevr Macro tcflag_t IMAXBEL
|
|
If this bit is set, then filling up the terminal input buffer sends a
|
|
BEL character (code @code{007}) to the terminal to ring the bell.
|
|
|
|
This is a BSD extension.
|
|
@end deftypevr
|
|
|
|
@node Output Modes
|
|
@subsection Output Modes
|
|
|
|
This section describes the terminal flags and fields that control how
|
|
output characters are translated and padded for display. All of these
|
|
are contained in the @code{c_oflag} member of the @w{@code{struct termios}}
|
|
structure.
|
|
|
|
The @code{c_oflag} member itself is an integer, and you change the flags
|
|
and fields using the operators @code{&}, @code{|}, and @code{^}. Don't
|
|
try to specify the entire value for @code{c_oflag}---instead, change
|
|
only specific flags and leave the rest untouched (@pxref{Setting
|
|
Modes}).
|
|
|
|
@comment termios.h
|
|
@comment POSIX.1
|
|
@deftypevr Macro tcflag_t OPOST
|
|
If this bit is set, output data is processed in some unspecified way so
|
|
that it is displayed appropriately on the terminal device. This
|
|
typically includes mapping newline characters (@code{'\n'}) onto
|
|
carriage return and linefeed pairs.
|
|
|
|
If this bit isn't set, the characters are transmitted as-is.
|
|
@end deftypevr
|
|
|
|
The following three bits are BSD features, and they exist only BSD
|
|
systems and the GNU system. They are effective only if @code{OPOST} is
|
|
set.
|
|
|
|
@comment termios.h
|
|
@comment BSD
|
|
@deftypevr Macro tcflag_t ONLCR
|
|
If this bit is set, convert the newline character on output into a pair
|
|
of characters, carriage return followed by linefeed.
|
|
@end deftypevr
|
|
|
|
@comment termios.h
|
|
@comment BSD
|
|
@deftypevr Macro tcflag_t OXTABS
|
|
If this bit is set, convert tab characters on output into the appropriate
|
|
number of spaces to emulate a tab stop every eight columns.
|
|
@end deftypevr
|
|
|
|
@comment termios.h
|
|
@comment BSD
|
|
@deftypevr Macro tcflag_t ONOEOT
|
|
If this bit is set, discard @kbd{C-d} characters (code @code{004}) on
|
|
output. These characters cause many dial-up terminals to disconnect.
|
|
@end deftypevr
|
|
|
|
@node Control Modes
|
|
@subsection Control Modes
|
|
|
|
This section describes the terminal flags and fields that control
|
|
parameters usually associated with asynchronous serial data
|
|
transmission. These flags may not make sense for other kinds of
|
|
terminal ports (such as a network connection pseudo-terminal). All of
|
|
these are contained in the @code{c_cflag} member of the @code{struct
|
|
termios} structure.
|
|
|
|
The @code{c_cflag} member itself is an integer, and you change the flags
|
|
and fields using the operators @code{&}, @code{|}, and @code{^}. Don't
|
|
try to specify the entire value for @code{c_cflag}---instead, change
|
|
only specific flags and leave the rest untouched (@pxref{Setting
|
|
Modes}).
|
|
|
|
@comment termios.h
|
|
@comment POSIX.1
|
|
@deftypevr Macro tcflag_t CLOCAL
|
|
If this bit is set, it indicates that the terminal is connected
|
|
``locally'' and that the modem status lines (such as carrier detect)
|
|
should be ignored.
|
|
@cindex modem status lines
|
|
@cindex carrier detect
|
|
|
|
On many systems if this bit is not set and you call @code{open} without
|
|
the @code{O_NONBLOCK} flag set, @code{open} blocks until a modem
|
|
connection is established.
|
|
|
|
If this bit is not set and a modem disconnect is detected, a
|
|
@code{SIGHUP} signal is sent to the controlling process group for the
|
|
terminal (if it has one). Normally, this causes the process to exit;
|
|
see @ref{Signal Handling}. Reading from the terminal after a disconnect
|
|
causes an end-of-file condition, and writing causes an @code{EIO} error
|
|
to be returned. The terminal device must be closed and reopened to
|
|
clear the condition.
|
|
@cindex modem disconnect
|
|
@end deftypevr
|
|
|
|
@comment termios.h
|
|
@comment POSIX.1
|
|
@deftypevr Macro tcflag_t HUPCL
|
|
If this bit is set, a modem disconnect is generated when all processes
|
|
that have the terminal device open have either closed the file or exited.
|
|
@end deftypevr
|
|
|
|
@comment termios.h
|
|
@comment POSIX.1
|
|
@deftypevr Macro tcflag_t CREAD
|
|
If this bit is set, input can be read from the terminal. Otherwise,
|
|
input is discarded when it arrives.
|
|
@end deftypevr
|
|
|
|
@comment termios.h
|
|
@comment POSIX.1
|
|
@deftypevr Macro tcflag_t CSTOPB
|
|
If this bit is set, two stop bits are used. Otherwise, only one stop bit
|
|
is used.
|
|
@end deftypevr
|
|
|
|
@comment termios.h
|
|
@comment POSIX.1
|
|
@deftypevr Macro tcflag_t PARENB
|
|
If this bit is set, generation and detection of a parity bit are enabled.
|
|
@xref{Input Modes}, for information on how input parity errors are handled.
|
|
|
|
If this bit is not set, no parity bit is added to output characters, and
|
|
input characters are not checked for correct parity.
|
|
@end deftypevr
|
|
|
|
@comment termios.h
|
|
@comment POSIX.1
|
|
@deftypevr Macro tcflag_t PARODD
|
|
This bit is only useful if @code{PARENB} is set. If @code{PARODD} is set,
|
|
odd parity is used, otherwise even parity is used.
|
|
@end deftypevr
|
|
|
|
The control mode flags also includes a field for the number of bits per
|
|
character. You can use the @code{CSIZE} macro as a mask to extract the
|
|
value, like this: @code{settings.c_cflag & CSIZE}.
|
|
|
|
@comment termios.h
|
|
@comment POSIX.1
|
|
@deftypevr Macro tcflag_t CSIZE
|
|
This is a mask for the number of bits per character.
|
|
@end deftypevr
|
|
|
|
@comment termios.h
|
|
@comment POSIX.1
|
|
@deftypevr Macro tcflag_t CS5
|
|
This specifies five bits per byte.
|
|
@end deftypevr
|
|
|
|
@comment termios.h
|
|
@comment POSIX.1
|
|
@deftypevr Macro tcflag_t CS6
|
|
This specifies six bits per byte.
|
|
@end deftypevr
|
|
|
|
@comment termios.h
|
|
@comment POSIX.1
|
|
@deftypevr Macro tcflag_t CS7
|
|
This specifies seven bits per byte.
|
|
@end deftypevr
|
|
|
|
@comment termios.h
|
|
@comment POSIX.1
|
|
@deftypevr Macro tcflag_t CS8
|
|
This specifies eight bits per byte.
|
|
@end deftypevr
|
|
|
|
The following four bits are BSD extensions; this exist only on BSD
|
|
systems and the GNU system.
|
|
|
|
@comment termios.h
|
|
@comment BSD
|
|
@deftypevr Macro tcflag_t CCTS_OFLOW
|
|
If this bit is set, enable flow control of output based on the CTS wire
|
|
(RS232 protocol).
|
|
@end deftypevr
|
|
|
|
@comment termios.h
|
|
@comment BSD
|
|
@deftypevr Macro tcflag_t CRTS_IFLOW
|
|
If this bit is set, enable flow control of input based on the RTS wire
|
|
(RS232 protocol).
|
|
@end deftypevr
|
|
|
|
@comment termios.h
|
|
@comment BSD
|
|
@deftypevr Macro tcflag_t MDMBUF
|
|
If this bit is set, enable carrier-based flow control of output.
|
|
@end deftypevr
|
|
|
|
@comment termios.h
|
|
@comment BSD
|
|
@deftypevr Macro tcflag_t CIGNORE
|
|
If this bit is set, it says to ignore the control modes and line speed
|
|
values entirely. This is only meaningful in a call to @code{tcsetattr}.
|
|
|
|
The @code{c_cflag} member and the line speed values returned by
|
|
@code{cfgetispeed} and @code{cfgetospeed} will be unaffected by the
|
|
call. @code{CIGNORE} is useful if you want to set all the software
|
|
modes in the other members, but leave the hardware details in
|
|
@code{c_cflag} unchanged. (This is how the @code{TCSASOFT} flag to
|
|
@code{tcsettattr} works.)
|
|
|
|
This bit is never set in the structure filled in by @code{tcgetattr}.
|
|
@end deftypevr
|
|
|
|
@node Local Modes
|
|
@subsection Local Modes
|
|
|
|
This section describes the flags for the @code{c_lflag} member of the
|
|
@code{struct termios} structure. These flags generally control
|
|
higher-level aspects of input processing than the input modes flags
|
|
described in @ref{Input Modes}, such as echoing, signals, and the choice
|
|
of canonical or noncanonical input.
|
|
|
|
The @code{c_lflag} member itself is an integer, and you change the flags
|
|
and fields using the operators @code{&}, @code{|}, and @code{^}. Don't
|
|
try to specify the entire value for @code{c_lflag}---instead, change
|
|
only specific flags and leave the rest untouched (@pxref{Setting
|
|
Modes}).
|
|
|
|
@comment termios.h
|
|
@comment POSIX.1
|
|
@deftypevr Macro tcflag_t ICANON
|
|
This bit, if set, enables canonical input processing mode. Otherwise,
|
|
input is processed in noncanonical mode. @xref{Canonical or Not}.
|
|
@end deftypevr
|
|
|
|
@comment termios.h
|
|
@comment POSIX.1
|
|
@deftypevr Macro tcflag_t ECHO
|
|
If this bit is set, echoing of input characters back to the terminal
|
|
is enabled.
|
|
@cindex echo of terminal input
|
|
@end deftypevr
|
|
|
|
@comment termios.h
|
|
@comment POSIX.1
|
|
@deftypevr Macro tcflag_t ECHOE
|
|
If this bit is set, echoing indicates erasure of input with the ERASE
|
|
character by erasing the last character in the current line from the
|
|
screen. Otherwise, the character erased is re-echoed to show what has
|
|
happened (suitable for a printing terminal).
|
|
|
|
This bit only controls the display behavior; the @code{ICANON} bit by
|
|
itself controls actual recognition of the ERASE character and erasure of
|
|
input, without which @code{ECHOE} is simply irrelevant.
|
|
@end deftypevr
|
|
|
|
@comment termios.h
|
|
@comment BSD
|
|
@deftypevr Macro tcflag_t ECHOPRT
|
|
This bit is like @code{ECHOE}, enables display of the ERASE character in
|
|
a way that is geared to a hardcopy terminal. When you type the ERASE
|
|
character, a @samp{\} character is printed followed by the first
|
|
character erased. Typing the ERASE character again just prints the next
|
|
character erased. Then, the next time you type a normal character, a
|
|
@samp{/} character is printed before the character echoes.
|
|
|
|
This is a BSD extension, and exists only in BSD systems and the
|
|
GNU system.
|
|
@end deftypevr
|
|
|
|
@comment termios.h
|
|
@comment POSIX.1
|
|
@deftypevr Macro tcflag_t ECHOK
|
|
This bit enables special display of the KILL character by moving to a
|
|
new line after echoing the KILL character normally. The behavior of
|
|
@code{ECHOKE} (below) is nicer to look at.
|
|
|
|
If this bit is not set, the KILL character echoes just as it would if it
|
|
were not the KILL character. Then it is up to the user to remember that
|
|
the KILL character has erased the preceding input; there is no
|
|
indication of this on the screen.
|
|
|
|
This bit only controls the display behavior; the @code{ICANON} bit by
|
|
itself controls actual recognition of the KILL character and erasure of
|
|
input, without which @code{ECHOK} is simply irrelevant.
|
|
@end deftypevr
|
|
|
|
@comment termios.h
|
|
@comment BSD
|
|
@deftypevr Macro tcflag_t ECHOKE
|
|
This bit is similar to @code{ECHOK}. It enables special display of the
|
|
KILL character by erasing on the screen the entire line that has been
|
|
killed. This is a BSD extension, and exists only in BSD systems and the
|
|
GNU system.
|
|
@end deftypevr
|
|
|
|
@comment termios.h
|
|
@comment POSIX.1
|
|
@deftypevr Macro tcflag_t ECHONL
|
|
If this bit is set and the @code{ICANON} bit is also set, then the
|
|
newline (@code{'\n'}) character is echoed even if the @code{ECHO} bit
|
|
is not set.
|
|
@end deftypevr
|
|
|
|
@comment termios.h
|
|
@comment BSD
|
|
@deftypevr Macro tcflag_t ECHOCTL
|
|
If this bit is set and the @code{ECHO} bit is also set, echo control
|
|
characters with @samp{^} followed by the corresponding text character.
|
|
Thus, control-A echoes as @samp{^A}. This is usually the preferred mode
|
|
for interactive input, because echoing a control character back to the
|
|
terminal could have some undesired effect on the terminal.
|
|
|
|
This is a BSD extension, and exists only in BSD systems and the
|
|
GNU system.
|
|
@end deftypevr
|
|
|
|
@comment termios.h
|
|
@comment POSIX.1
|
|
@deftypevr Macro tcflag_t ISIG
|
|
This bit controls whether the INTR, QUIT, and SUSP characters are
|
|
recognized. The functions associated with these characters are performed
|
|
if and only if this bit is set. Being in canonical or noncanonical
|
|
input mode has no affect on the interpretation of these characters.
|
|
|
|
You should use caution when disabling recognition of these characters.
|
|
Programs that cannot be interrupted interactively are very
|
|
user-unfriendly. If you clear this bit, your program should provide
|
|
some alternate interface that allows the user to interactively send the
|
|
signals associated with these characters, or to escape from the program.
|
|
@cindex interactive signals, from terminal
|
|
|
|
@xref{Signal Characters}.
|
|
@end deftypevr
|
|
|
|
@comment termios.h
|
|
@comment POSIX.1
|
|
@deftypevr Macro tcflag_t IEXTEN
|
|
POSIX.1 gives @code{IEXTEN} implementation-defined meaning,
|
|
so you cannot rely on this interpretation on all systems.
|
|
|
|
On BSD systems and the GNU system, it enables the LNEXT and DISCARD characters.
|
|
@xref{Other Special}.
|
|
@end deftypevr
|
|
|
|
@comment termios.h
|
|
@comment POSIX.1
|
|
@deftypevr Macro tcflag_t NOFLSH
|
|
Normally, the INTR, QUIT, and SUSP characters cause input and output
|
|
queues for the terminal to be cleared. If this bit is set, the queues
|
|
are not cleared.
|
|
@end deftypevr
|
|
|
|
@comment termios.h
|
|
@comment POSIX.1
|
|
@deftypevr Macro tcflag_t TOSTOP
|
|
If this bit is set and the system supports job control, then
|
|
@code{SIGTTOU} signals are generated by background processes that
|
|
attempt to write to the terminal. @xref{Access to the Terminal}.
|
|
@end deftypevr
|
|
|
|
The following bits are BSD extensions; they exist only in BSD systems
|
|
and the GNU system.
|
|
|
|
@comment termios.h
|
|
@comment BSD
|
|
@deftypevr Macro tcflag_t ALTWERASE
|
|
This bit determines how far the WERASE character should erase. The
|
|
WERASE character erases back to the beginning of a word; the question
|
|
is, where do words begin?
|
|
|
|
If this bit is clear, then the beginning of a word is a nonwhitespace
|
|
character following a whitespace character. If the bit is set, then the
|
|
beginning of a word is an alphanumeric character or underscore following
|
|
a character which is none of those.
|
|
|
|
@xref{Editing Characters}, for more information about the WERASE character.
|
|
@end deftypevr
|
|
|
|
@comment termios.h
|
|
@comment BSD
|
|
@deftypevr Macro tcflag_t FLUSHO
|
|
This is the bit that toggles when the user types the DISCARD character.
|
|
While this bit is set, all output is discarded. @xref{Other Special}.
|
|
@end deftypevr
|
|
|
|
@comment termios.h
|
|
@comment BSD
|
|
@deftypevr Macro tcflag_t NOKERNINFO
|
|
Setting this bit disables handling of the STATUS character.
|
|
@xref{Other Special}.
|
|
@end deftypevr
|
|
|
|
@comment termios.h
|
|
@comment BSD
|
|
@deftypevr Macro tcflag_t PENDIN
|
|
If this bit is set, it indicates that there is a line of input that
|
|
needs to be reprinted. Typing the REPRINT character sets this bit; the
|
|
bit remains set until reprinting is finished. @xref{Editing Characters}.
|
|
@end deftypevr
|
|
|
|
@c EXTPROC is too obscure to document now. --roland
|
|
|
|
@node Line Speed
|
|
@subsection Line Speed
|
|
@cindex line speed
|
|
@cindex baud rate
|
|
@cindex terminal line speed
|
|
@cindex terminal line speed
|
|
|
|
The terminal line speed tells the computer how fast to read and write
|
|
data on the terminal.
|
|
|
|
If the terminal is connected to a real serial line, the terminal speed
|
|
you specify actually controls the line---if it doesn't match the
|
|
terminal's own idea of the speed, communication does not work. Real
|
|
serial ports accept only certain standard speeds. Also, particular
|
|
hardware may not support even all the standard speeds. Specifying a
|
|
speed of zero hangs up a dialup connection and turns off modem control
|
|
signals.
|
|
|
|
If the terminal is not a real serial line (for example, if it is a
|
|
network connection), then the line speed won't really affect data
|
|
transmission speed, but some programs will use it to determine the
|
|
amount of padding needed. It's best to specify a line speed value that
|
|
matches the actual speed of the actual terminal, but you can safely
|
|
experiment with different values to vary the amount of padding.
|
|
|
|
There are actually two line speeds for each terminal, one for input and
|
|
one for output. You can set them independently, but most often
|
|
terminals use the same speed for both directions.
|
|
|
|
The speed values are stored in the @code{struct termios} structure, but
|
|
don't try to access them in the @code{struct termios} structure
|
|
directly. Instead, you should use the following functions to read and
|
|
store them:
|
|
|
|
@comment termios.h
|
|
@comment POSIX.1
|
|
@deftypefun speed_t cfgetospeed (const struct termios *@var{termios-p})
|
|
This function returns the output line speed stored in the structure
|
|
@code{*@var{termios-p}}.
|
|
@end deftypefun
|
|
|
|
@comment termios.h
|
|
@comment POSIX.1
|
|
@deftypefun speed_t cfgetispeed (const struct termios *@var{termios-p})
|
|
This function returns the input line speed stored in the structure
|
|
@code{*@var{termios-p}}.
|
|
@end deftypefun
|
|
|
|
@comment termios.h
|
|
@comment POSIX.1
|
|
@deftypefun int cfsetospeed (struct termios *@var{termios-p}, speed_t @var{speed})
|
|
This function stores @var{speed} in @code{*@var{termios-p}} as the output
|
|
speed. The normal return value is @math{0}; a value of @math{-1}
|
|
indicates an error. If @var{speed} is not a speed, @code{cfsetospeed}
|
|
returns @math{-1}.
|
|
@end deftypefun
|
|
|
|
@comment termios.h
|
|
@comment POSIX.1
|
|
@deftypefun int cfsetispeed (struct termios *@var{termios-p}, speed_t @var{speed})
|
|
This function stores @var{speed} in @code{*@var{termios-p}} as the input
|
|
speed. The normal return value is @math{0}; a value of @math{-1}
|
|
indicates an error. If @var{speed} is not a speed, @code{cfsetospeed}
|
|
returns @math{-1}.
|
|
@end deftypefun
|
|
|
|
@comment termios.h
|
|
@comment BSD
|
|
@deftypefun int cfsetspeed (struct termios *@var{termios-p}, speed_t @var{speed})
|
|
This function stores @var{speed} in @code{*@var{termios-p}} as both the
|
|
input and output speeds. The normal return value is @math{0}; a value
|
|
of @math{-1} indicates an error. If @var{speed} is not a speed,
|
|
@code{cfsetspeed} returns @math{-1}. This function is an extension in
|
|
4.4 BSD.
|
|
@end deftypefun
|
|
|
|
@comment termios.h
|
|
@comment POSIX.1
|
|
@deftp {Data Type} speed_t
|
|
The @code{speed_t} type is an unsigned integer data type used to
|
|
represent line speeds.
|
|
@end deftp
|
|
|
|
The functions @code{cfsetospeed} and @code{cfsetispeed} report errors
|
|
only for speed values that the system simply cannot handle. If you
|
|
specify a speed value that is basically acceptable, then those functions
|
|
will succeed. But they do not check that a particular hardware device
|
|
can actually support the specified speeds---in fact, they don't know
|
|
which device you plan to set the speed for. If you use @code{tcsetattr}
|
|
to set the speed of a particular device to a value that it cannot
|
|
handle, @code{tcsetattr} returns @math{-1}.
|
|
|
|
@strong{Portability note:} In the GNU library, the functions above
|
|
accept speeds measured in bits per second as input, and return speed
|
|
values measured in bits per second. Other libraries require speeds to
|
|
be indicated by special codes. For POSIX.1 portability, you must use
|
|
one of the following symbols to represent the speed; their precise
|
|
numeric values are system-dependent, but each name has a fixed meaning:
|
|
@code{B110} stands for 110 bps, @code{B300} for 300 bps, and so on.
|
|
There is no portable way to represent any speed but these, but these are
|
|
the only speeds that typical serial lines can support.
|
|
|
|
@comment termios.h
|
|
@comment POSIX.1
|
|
@vindex B0
|
|
@comment termios.h
|
|
@comment POSIX.1
|
|
@vindex B50
|
|
@comment termios.h
|
|
@comment POSIX.1
|
|
@vindex B75
|
|
@comment termios.h
|
|
@comment POSIX.1
|
|
@vindex B110
|
|
@comment termios.h
|
|
@comment POSIX.1
|
|
@vindex B134
|
|
@comment termios.h
|
|
@comment POSIX.1
|
|
@vindex B150
|
|
@comment termios.h
|
|
@comment POSIX.1
|
|
@vindex B200
|
|
@comment termios.h
|
|
@comment POSIX.1
|
|
@vindex B300
|
|
@comment termios.h
|
|
@comment POSIX.1
|
|
@vindex B600
|
|
@comment termios.h
|
|
@comment POSIX.1
|
|
@vindex B1200
|
|
@comment termios.h
|
|
@comment POSIX.1
|
|
@vindex B1800
|
|
@comment termios.h
|
|
@comment POSIX.1
|
|
@vindex B2400
|
|
@comment termios.h
|
|
@comment POSIX.1
|
|
@vindex B4800
|
|
@comment termios.h
|
|
@comment POSIX.1
|
|
@vindex B9600
|
|
@comment termios.h
|
|
@comment POSIX.1
|
|
@vindex B19200
|
|
@comment termios.h
|
|
@comment POSIX.1
|
|
@vindex B38400
|
|
@comment termios.h
|
|
@comment GNU
|
|
@vindex B57600
|
|
@comment termios.h
|
|
@comment GNU
|
|
@vindex B115200
|
|
@comment termios.h
|
|
@comment GNU
|
|
@vindex B230400
|
|
@comment termios.h
|
|
@comment GNU
|
|
@vindex B460800
|
|
@smallexample
|
|
B0 B50 B75 B110 B134 B150 B200
|
|
B300 B600 B1200 B1800 B2400 B4800
|
|
B9600 B19200 B38400 B57600 B115200
|
|
B230400 B460800
|
|
@end smallexample
|
|
|
|
@vindex EXTA
|
|
@vindex EXTB
|
|
BSD defines two additional speed symbols as aliases: @code{EXTA} is an
|
|
alias for @code{B19200} and @code{EXTB} is an alias for @code{B38400}.
|
|
These aliases are obsolete.
|
|
|
|
@node Special Characters
|
|
@subsection Special Characters
|
|
|
|
In canonical input, the terminal driver recognizes a number of special
|
|
characters which perform various control functions. These include the
|
|
ERASE character (usually @key{DEL}) for editing input, and other editing
|
|
characters. The INTR character (normally @kbd{C-c}) for sending a
|
|
@code{SIGINT} signal, and other signal-raising characters, may be
|
|
available in either canonical or noncanonical input mode. All these
|
|
characters are described in this section.
|
|
|
|
The particular characters used are specified in the @code{c_cc} member
|
|
of the @code{struct termios} structure. This member is an array; each
|
|
element specifies the character for a particular role. Each element has
|
|
a symbolic constant that stands for the index of that element---for
|
|
example, @code{VINTR} is the index of the element that specifies the INTR
|
|
character, so storing @code{'='} in @code{@var{termios}.c_cc[VINTR]}
|
|
specifies @samp{=} as the INTR character.
|
|
|
|
@vindex _POSIX_VDISABLE
|
|
On some systems, you can disable a particular special character function
|
|
by specifying the value @code{_POSIX_VDISABLE} for that role. This
|
|
value is unequal to any possible character code. @xref{Options for
|
|
Files}, for more information about how to tell whether the operating
|
|
system you are using supports @code{_POSIX_VDISABLE}.
|
|
|
|
@menu
|
|
* Editing Characters:: Special characters that terminate lines and
|
|
delete text, and other editing functions.
|
|
* Signal Characters:: Special characters that send or raise signals
|
|
to or for certain classes of processes.
|
|
* Start/Stop Characters:: Special characters that suspend or resume
|
|
suspended output.
|
|
* Other Special:: Other special characters for BSD systems:
|
|
they can discard output, and print status.
|
|
@end menu
|
|
|
|
@node Editing Characters
|
|
@subsubsection Characters for Input Editing
|
|
|
|
These special characters are active only in canonical input mode.
|
|
@xref{Canonical or Not}.
|
|
|
|
@comment termios.h
|
|
@comment POSIX.1
|
|
@deftypevr Macro int VEOF
|
|
@cindex EOF character
|
|
This is the subscript for the EOF character in the special control
|
|
character array. @code{@var{termios}.c_cc[VEOF]} holds the character
|
|
itself.
|
|
|
|
The EOF character is recognized only in canonical input mode. It acts
|
|
as a line terminator in the same way as a newline character, but if the
|
|
EOF character is typed at the beginning of a line it causes @code{read}
|
|
to return a byte count of zero, indicating end-of-file. The EOF
|
|
character itself is discarded.
|
|
|
|
Usually, the EOF character is @kbd{C-d}.
|
|
@end deftypevr
|
|
|
|
@comment termios.h
|
|
@comment POSIX.1
|
|
@deftypevr Macro int VEOL
|
|
@cindex EOL character
|
|
This is the subscript for the EOL character in the special control
|
|
character array. @code{@var{termios}.c_cc[VEOL]} holds the character
|
|
itself.
|
|
|
|
The EOL character is recognized only in canonical input mode. It acts
|
|
as a line terminator, just like a newline character. The EOL character
|
|
is not discarded; it is read as the last character in the input line.
|
|
|
|
@c !!! example: this is set to ESC by 4.3 csh with "set filec" so it can
|
|
@c complete partial lines without using cbreak or raw mode.
|
|
|
|
You don't need to use the EOL character to make @key{RET} end a line.
|
|
Just set the ICRNL flag. In fact, this is the default state of
|
|
affairs.
|
|
@end deftypevr
|
|
|
|
@comment termios.h
|
|
@comment BSD
|
|
@deftypevr Macro int VEOL2
|
|
@cindex EOL2 character
|
|
This is the subscript for the EOL2 character in the special control
|
|
character array. @code{@var{termios}.c_cc[VEOL2]} holds the character
|
|
itself.
|
|
|
|
The EOL2 character works just like the EOL character (see above), but it
|
|
can be a different character. Thus, you can specify two characters to
|
|
terminate an input line, by setting EOL to one of them and EOL2 to the
|
|
other.
|
|
|
|
The EOL2 character is a BSD extension; it exists only on BSD systems
|
|
and the GNU system.
|
|
@end deftypevr
|
|
|
|
@comment termios.h
|
|
@comment POSIX.1
|
|
@deftypevr Macro int VERASE
|
|
@cindex ERASE character
|
|
This is the subscript for the ERASE character in the special control
|
|
character array. @code{@var{termios}.c_cc[VERASE]} holds the
|
|
character itself.
|
|
|
|
The ERASE character is recognized only in canonical input mode. When
|
|
the user types the erase character, the previous character typed is
|
|
discarded. (If the terminal generates multibyte character sequences,
|
|
this may cause more than one byte of input to be discarded.) This
|
|
cannot be used to erase past the beginning of the current line of text.
|
|
The ERASE character itself is discarded.
|
|
@c !!! mention ECHOE here
|
|
|
|
Usually, the ERASE character is @key{DEL}.
|
|
@end deftypevr
|
|
|
|
@comment termios.h
|
|
@comment BSD
|
|
@deftypevr Macro int VWERASE
|
|
@cindex WERASE character
|
|
This is the subscript for the WERASE character in the special control
|
|
character array. @code{@var{termios}.c_cc[VWERASE]} holds the character
|
|
itself.
|
|
|
|
The WERASE character is recognized only in canonical mode. It erases an
|
|
entire word of prior input, and any whitespace after it; whitespace
|
|
characters before the word are not erased.
|
|
|
|
The definition of a ``word'' depends on the setting of the
|
|
@code{ALTWERASE} mode; @pxref{Local Modes}.
|
|
|
|
If the @code{ALTWERASE} mode is not set, a word is defined as a sequence
|
|
of any characters except space or tab.
|
|
|
|
If the @code{ALTWERASE} mode is set, a word is defined as a sequence of
|
|
characters containing only letters, numbers, and underscores, optionally
|
|
followed by one character that is not a letter, number, or underscore.
|
|
|
|
The WERASE character is usually @kbd{C-w}.
|
|
|
|
This is a BSD extension.
|
|
@end deftypevr
|
|
|
|
@comment termios.h
|
|
@comment POSIX.1
|
|
@deftypevr Macro int VKILL
|
|
@cindex KILL character
|
|
This is the subscript for the KILL character in the special control
|
|
character array. @code{@var{termios}.c_cc[VKILL]} holds the character
|
|
itself.
|
|
|
|
The KILL character is recognized only in canonical input mode. When the
|
|
user types the kill character, the entire contents of the current line
|
|
of input are discarded. The kill character itself is discarded too.
|
|
|
|
The KILL character is usually @kbd{C-u}.
|
|
@end deftypevr
|
|
|
|
@comment termios.h
|
|
@comment BSD
|
|
@deftypevr Macro int VREPRINT
|
|
@cindex REPRINT character
|
|
This is the subscript for the REPRINT character in the special control
|
|
character array. @code{@var{termios}.c_cc[VREPRINT]} holds the character
|
|
itself.
|
|
|
|
The REPRINT character is recognized only in canonical mode. It reprints
|
|
the current input line. If some asynchronous output has come while you
|
|
are typing, this lets you see the line you are typing clearly again.
|
|
|
|
The REPRINT character is usually @kbd{C-r}.
|
|
|
|
This is a BSD extension.
|
|
@end deftypevr
|
|
|
|
@node Signal Characters
|
|
@subsubsection Characters that Cause Signals
|
|
|
|
These special characters may be active in either canonical or noncanonical
|
|
input mode, but only when the @code{ISIG} flag is set (@pxref{Local
|
|
Modes}).
|
|
|
|
@comment termios.h
|
|
@comment POSIX.1
|
|
@deftypevr Macro int VINTR
|
|
@cindex INTR character
|
|
@cindex interrupt character
|
|
This is the subscript for the INTR character in the special control
|
|
character array. @code{@var{termios}.c_cc[VINTR]} holds the character
|
|
itself.
|
|
|
|
The INTR (interrupt) character raises a @code{SIGINT} signal for all
|
|
processes in the foreground job associated with the terminal. The INTR
|
|
character itself is then discarded. @xref{Signal Handling}, for more
|
|
information about signals.
|
|
|
|
Typically, the INTR character is @kbd{C-c}.
|
|
@end deftypevr
|
|
|
|
@comment termios.h
|
|
@comment POSIX.1
|
|
@deftypevr Macro int VQUIT
|
|
@cindex QUIT character
|
|
This is the subscript for the QUIT character in the special control
|
|
character array. @code{@var{termios}.c_cc[VQUIT]} holds the character
|
|
itself.
|
|
|
|
The QUIT character raises a @code{SIGQUIT} signal for all processes in
|
|
the foreground job associated with the terminal. The QUIT character
|
|
itself is then discarded. @xref{Signal Handling}, for more information
|
|
about signals.
|
|
|
|
Typically, the QUIT character is @kbd{C-\}.
|
|
@end deftypevr
|
|
|
|
@comment termios.h
|
|
@comment POSIX.1
|
|
@deftypevr Macro int VSUSP
|
|
@cindex SUSP character
|
|
@cindex suspend character
|
|
This is the subscript for the SUSP character in the special control
|
|
character array. @code{@var{termios}.c_cc[VSUSP]} holds the character
|
|
itself.
|
|
|
|
The SUSP (suspend) character is recognized only if the implementation
|
|
supports job control (@pxref{Job Control}). It causes a @code{SIGTSTP}
|
|
signal to be sent to all processes in the foreground job associated with
|
|
the terminal. The SUSP character itself is then discarded.
|
|
@xref{Signal Handling}, for more information about signals.
|
|
|
|
Typically, the SUSP character is @kbd{C-z}.
|
|
@end deftypevr
|
|
|
|
Few applications disable the normal interpretation of the SUSP
|
|
character. If your program does this, it should provide some other
|
|
mechanism for the user to stop the job. When the user invokes this
|
|
mechanism, the program should send a @code{SIGTSTP} signal to the
|
|
process group of the process, not just to the process itself.
|
|
@xref{Signaling Another Process}.
|
|
|
|
@comment termios.h
|
|
@comment BSD
|
|
@deftypevr Macro int VDSUSP
|
|
@cindex DSUSP character
|
|
@cindex delayed suspend character
|
|
This is the subscript for the DSUSP character in the special control
|
|
character array. @code{@var{termios}.c_cc[VDSUSP]} holds the character
|
|
itself.
|
|
|
|
The DSUSP (suspend) character is recognized only if the implementation
|
|
supports job control (@pxref{Job Control}). It sends a @code{SIGTSTP}
|
|
signal, like the SUSP character, but not right away---only when the
|
|
program tries to read it as input. Not all systems with job control
|
|
support DSUSP; only BSD-compatible systems (including the GNU system).
|
|
|
|
@xref{Signal Handling}, for more information about signals.
|
|
|
|
Typically, the DSUSP character is @kbd{C-y}.
|
|
@end deftypevr
|
|
|
|
@node Start/Stop Characters
|
|
@subsubsection Special Characters for Flow Control
|
|
|
|
These special characters may be active in either canonical or noncanonical
|
|
input mode, but their use is controlled by the flags @code{IXON} and
|
|
@code{IXOFF} (@pxref{Input Modes}).
|
|
|
|
@comment termios.h
|
|
@comment POSIX.1
|
|
@deftypevr Macro int VSTART
|
|
@cindex START character
|
|
This is the subscript for the START character in the special control
|
|
character array. @code{@var{termios}.c_cc[VSTART]} holds the
|
|
character itself.
|
|
|
|
The START character is used to support the @code{IXON} and @code{IXOFF}
|
|
input modes. If @code{IXON} is set, receiving a START character resumes
|
|
suspended output; the START character itself is discarded. If
|
|
@code{IXANY} is set, receiving any character at all resumes suspended
|
|
output; the resuming character is not discarded unless it is the START
|
|
character. @code{IXOFF} is set, the system may also transmit START
|
|
characters to the terminal.
|
|
|
|
The usual value for the START character is @kbd{C-q}. You may not be
|
|
able to change this value---the hardware may insist on using @kbd{C-q}
|
|
regardless of what you specify.
|
|
@end deftypevr
|
|
|
|
@comment termios.h
|
|
@comment POSIX.1
|
|
@deftypevr Macro int VSTOP
|
|
@cindex STOP character
|
|
This is the subscript for the STOP character in the special control
|
|
character array. @code{@var{termios}.c_cc[VSTOP]} holds the character
|
|
itself.
|
|
|
|
The STOP character is used to support the @code{IXON} and @code{IXOFF}
|
|
input modes. If @code{IXON} is set, receiving a STOP character causes
|
|
output to be suspended; the STOP character itself is discarded. If
|
|
@code{IXOFF} is set, the system may also transmit STOP characters to the
|
|
terminal, to prevent the input queue from overflowing.
|
|
|
|
The usual value for the STOP character is @kbd{C-s}. You may not be
|
|
able to change this value---the hardware may insist on using @kbd{C-s}
|
|
regardless of what you specify.
|
|
@end deftypevr
|
|
|
|
@node Other Special
|
|
@subsubsection Other Special Characters
|
|
|
|
These special characters exist only in BSD systems and the GNU system.
|
|
|
|
@comment termios.h
|
|
@comment BSD
|
|
@deftypevr Macro int VLNEXT
|
|
@cindex LNEXT character
|
|
This is the subscript for the LNEXT character in the special control
|
|
character array. @code{@var{termios}.c_cc[VLNEXT]} holds the character
|
|
itself.
|
|
|
|
The LNEXT character is recognized only when @code{IEXTEN} is set, but in
|
|
both canonical and noncanonical mode. It disables any special
|
|
significance of the next character the user types. Even if the
|
|
character would normally perform some editing 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 BSD Terminal Modes
|
|
@section BSD Terminal Modes
|
|
@cindex terminal modes, BSD
|
|
|
|
The usual way to get and set terminal modes is with the functions described
|
|
in @ref{Terminal Modes}. However, on some systems you can use the
|
|
BSD-derived functions in this section to do some of the same thing. On
|
|
many systems, these functions do not exist. Even with the GNU C library,
|
|
the functions simply fail with @code{errno} = @code{ENOSYS} with many
|
|
kernels, including Linux.
|
|
|
|
The symbols used in this section are declared in @file{sgtty.h}.
|
|
|
|
@comment termios.h
|
|
@comment BSD
|
|
@deftp {Data Type} {struct sgttyb}
|
|
This structure is an input or output parameter list for @code{gtty} and
|
|
@code{stty}.
|
|
|
|
@table @code
|
|
@item char sg_ispeed
|
|
Line speed for input
|
|
@item char sg_ospeed
|
|
Line speed for output
|
|
@item char sg_erase
|
|
Erase character
|
|
@item char sg_kill
|
|
Kill character
|
|
@item int sg_flags
|
|
Various flags
|
|
@end table
|
|
@end deftp
|
|
|
|
@comment sgtty.h
|
|
@comment BSD
|
|
@deftypefun int gtty (int @var{filedes}, struct sgttyb *@var{attributes})
|
|
This function gets the attributes of a terminal.
|
|
|
|
@code{gtty} sets *@var{attributes} to describe the terminal attributes
|
|
of the terminal which is open with file descriptor @var{filedes}.
|
|
@end deftypefun
|
|
|
|
@comment sgtty.h
|
|
@comment BSD
|
|
@deftypefun int stty (int @var{filedes}, struct sgttyb * attributes)
|
|
|
|
This function sets the attributes of a terminal.
|
|
|
|
@code{stty} sets the terminal attributes of the terminal which is open with
|
|
file descriptor @var{filedes} to those described by *@var{filedes}.
|
|
@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 @math{-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.
|
|
|
|
This function is a cancelation point in multi-threaded programs. This
|
|
is a problem if the thread allocates some resources (like memory, file
|
|
descriptors, semaphores or whatever) at the time @code{tcdrain} is
|
|
called. If the thread gets canceled these resources stay allocated
|
|
until the program ends. To avoid this calls to @code{tcdrain} should be
|
|
protected using cancelation handlers.
|
|
@c ref pthread_cleanup_push / pthread_cleanup_pop
|
|
|
|
The return value is normally zero. In the event of an error, a value
|
|
of @math{-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 @math{-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 @math{-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.
|
|
|
|
|
|
@node Pseudo-Terminals
|
|
@section Pseudo-Terminals
|
|
@cindex pseudo-terminals
|
|
|
|
A @dfn{pseudo-terminal} is a special interprocess communication channel
|
|
that acts like a terminal. One end of the channel is called the
|
|
@dfn{master} side or @dfn{master pseudo-terminal device}, the other side
|
|
is called the @dfn{slave} side. Data written to the master side is
|
|
received by the slave side as if it was the result of a user typing at
|
|
an ordinary terminal, and data written to the slave side is sent to the
|
|
master side as if it was written on an ordinary terminal.
|
|
|
|
Pseudo terminals are the way programs like @code{xterm} and @code{emacs}
|
|
implement their terminal emulation functionality.
|
|
|
|
@menu
|
|
* Allocation:: Allocating a pseudo terminal.
|
|
* Pseudo-Terminal Pairs:: How to open both sides of a
|
|
pseudo-terminal in a single operation.
|
|
@end menu
|
|
|
|
@node Allocation
|
|
@subsection Allocating Pseudo-Terminals
|
|
@cindex allocating pseudo-terminals
|
|
|
|
@pindex stdlib.h
|
|
This subsection describes functions for allocating a pseudo-terminal,
|
|
and for making this pseudo-terminal available for actual use. These
|
|
functions are declared in the header file @file{stdlib.h}.
|
|
|
|
@comment stdlib.h
|
|
@comment GNU
|
|
@deftypefun int getpt (void)
|
|
The @code{getpt} function returns a new file descriptor for the next
|
|
available master pseudo-terminal. The normal return value from
|
|
@code{getpt} is a non-negative integer file descriptor. In the case of
|
|
an error, a value of @math{-1} is returned instead. The following
|
|
@code{errno} conditions are defined for this function:
|
|
|
|
@table @code
|
|
@item ENOENT
|
|
There are no free master pseudo-terminals available.
|
|
@end table
|
|
|
|
This function is a GNU extension.
|
|
@end deftypefun
|
|
|
|
@comment stdlib.h
|
|
@comment SVID, XPG4.2
|
|
@deftypefun int grantpt (int @var{filedes})
|
|
The @code{grantpt} function changes the ownership and access permission
|
|
of the slave pseudo-terminal device corresponding to the master
|
|
pseudo-terminal device associated with the file descriptor
|
|
@var{filedes}. The owner is set from the real user ID of the calling
|
|
process (@pxref{Process Persona}), and the group is set to a special
|
|
group (typically @dfn{tty}) or from the real group ID of the calling
|
|
process. The access permission is set such that the file is both
|
|
readable and writable by the owner and only writable by the group.
|
|
|
|
On some systems this function is implemented by invoking a special
|
|
@code{setuid} root program (@pxref{How Change Persona}). As a
|
|
consequence, installing a signal handler for the @code{SIGCHLD} signal
|
|
(@pxref{Job Control Signals}) may interfere with a call to
|
|
@code{grantpt}.
|
|
|
|
The normal return value from @code{grantpt} is @math{0}; a value of
|
|
@math{-1} is returned in case of failure. 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 ENINVAL
|
|
The @var{filedes} argument is not associated with a master pseudo-terminal
|
|
device.
|
|
|
|
@item EACCESS
|
|
The slave pseudo-terminal device corresponding to the master associated
|
|
with @var{filedes} could not be accessed.
|
|
@end table
|
|
|
|
@end deftypefun
|
|
|
|
@comment stdlib.h
|
|
@comment SVID, XPG4.2
|
|
@deftypefun int unlockpt (int @var{filedes})
|
|
The @code{unlockpt} function unlocks the slave pseudo-terminal device
|
|
corresponding to the master pseudo-terminal device associated with the
|
|
file descriptor @var{filedes}. On many systems, the slave can only be
|
|
opened after unlocking, so portable applications should always call
|
|
@code{unlockpt} before trying to open the slave.
|
|
|
|
The normal return value from @code{unlockpt} is @math{0}; a value of
|
|
@math{-1} is returned in case of failure. 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 EINVAL
|
|
The @var{filedes} argument is not associated with a master pseudo-terminal
|
|
device.
|
|
@end table
|
|
@end deftypefun
|
|
|
|
@comment stdlib.h
|
|
@comment SVID, XPG4.2
|
|
@deftypefun {char *} ptsname (int @var{filedes})
|
|
If the file descriptor @var{filedes} is associated with a
|
|
master pseudo-terminal device, the @code{ptsname} function returns a
|
|
pointer to a statically-allocated, null-terminated string containing the
|
|
file name of the associated slave pseudo-terminal file. This string
|
|
might be overwritten by subsequent calls to @code{ptsname}.
|
|
@end deftypefun
|
|
|
|
@comment stdlib.h
|
|
@comment GNU
|
|
@deftypefun int ptsname_r (int @var{filedes}, char *@var{buf}, size_t @var{len})
|
|
The @code{ptsname_r} function is similar to the @code{ptsname} function
|
|
except that it places its result into the user-specified buffer starting
|
|
at @var{buf} with length @var{len}.
|
|
|
|
This function is a GNU extension.
|
|
@end deftypefun
|
|
|
|
@strong{Portability Note:} On @w{System V} derived systems, the file
|
|
returned by the @code{ptsname} and @code{ptsname_r} functions may be
|
|
STREAMS-based, and therefore require additional processing after opening
|
|
before it actually behaves as a pseudo terminal.
|
|
@c FIXME: xref STREAMS
|
|
|
|
Typical usage of these functions is illustrated by the following example:
|
|
@smallexample
|
|
int
|
|
open_pty_pair (int *amaster, int *aslave)
|
|
@{
|
|
int master, slave;
|
|
char *name
|
|
|
|
master = getpt ();
|
|
if (master < 0)
|
|
return 0;
|
|
|
|
if (grantpt (master) < 0 || unlockpt (master) < 0)
|
|
goto close_master;
|
|
name = ptsname (master);
|
|
if (name == NULL)
|
|
goto close_master;
|
|
|
|
slave = open (name, O_RDWR);
|
|
if (slave == -1)
|
|
goto close_master;
|
|
|
|
if (isastream (slave))
|
|
@{
|
|
if (ioctl (slave, I_PUSH, "ptem") < 0
|
|
|| ioctl (slave, I_PUSH, "ldterm") < 0)
|
|
goto close_slave;
|
|
@}
|
|
|
|
*amaster = master;
|
|
*aslave = slave;
|
|
return 1;
|
|
|
|
close_slave:
|
|
close (slave);
|
|
|
|
close_master:
|
|
close (master);
|
|
return 0;
|
|
@}
|
|
@end smallexample
|
|
|
|
@node Pseudo-Terminal Pairs
|
|
@subsection Opening a Pseudo-Terminal Pair
|
|
@cindex opening a pseudo-terminal pair
|
|
|
|
These functions, derived from BSD, are available in the separate
|
|
@file{libutil} library, and declared in @file{pty.h}.
|
|
|
|
@comment pty.h
|
|
@comment BSD
|
|
@deftypefun int openpty (int *@var{amaster}, int *@var{aslave}, char *@var{name}, struct termios *@var{termp}, struct winsize *@var{winp})
|
|
This function allocates and opens a pseudo-terminal pair, returning the
|
|
file descriptor for the master in @var{*amaster}, and the file
|
|
descriptor for the slave in @var{*aslave}. If the argument @var{name}
|
|
is not a null pointer, the file name of the slave pseudo-terminal
|
|
device is stored in @code{*name}. If @var{termp} is not a null pointer,
|
|
the terminal attributes of the slave are set to the ones specified in
|
|
the structure that @var{termp} points to (@pxref{Terminal Modes}).
|
|
Likewise, if the @var{winp} is not a null pointer, the screen size of
|
|
the slave is set to the values specified in the structure that
|
|
@var{winp} points to.
|
|
|
|
The normal return value from @code{openpty} is @math{0}; a value of
|
|
@math{-1} is returned in case of failure. The following @code{errno}
|
|
conditions are defined for this function:
|
|
|
|
@table @code
|
|
@item ENOENT
|
|
There are no free pseudo-terminal pairs available.
|
|
@end table
|
|
|
|
@strong{Warning:} Using the @code{openpty} function with @var{name} not
|
|
set to @code{NULL} is @strong{very dangerous} because it provides no
|
|
protection against overflowing the string @var{name}. You should use
|
|
the @code{ttyname} function on the file descriptor returned in
|
|
@var{*slave} to find out the file name of the slave pseudo-terminal
|
|
device instead.
|
|
@end deftypefun
|
|
|
|
@comment pty.h
|
|
@comment BSD
|
|
@deftypefun int forkpty (int *@var{amaster}, char *@var{name}, struct termios *@var{termp}, struct winsize *@var{winp})
|
|
This function is similar to the @code{openpty} function, but in
|
|
addition, forks a new process (@pxref{Creating a Process}) and makes the
|
|
newly opened slave pseudo-terminal device the controlling terminal
|
|
(@pxref{Controlling Terminal}) for the child process.
|
|
|
|
If the operation is successful, there are then both parent and child
|
|
processes and both see @code{forkpty} return, but with different values:
|
|
it returns a value of @math{0} in the child process and returns the child's
|
|
process ID in the parent process.
|
|
|
|
If the allocation of a pseudo-terminal pair or the process creation
|
|
failed, @code{forkpty} returns a value of @math{-1} in the parent
|
|
process.
|
|
|
|
@strong{Warning:} The @code{forkpty} function has the same problems with
|
|
respect to the @var{name} argument as @code{openpty}.
|
|
@end deftypefun
|