|
Packit |
6c4009 |
@node Low-Level Terminal Interface, Syslog, Sockets, Top
|
|
Packit |
6c4009 |
@c %MENU% How to change the characteristics of a terminal device
|
|
Packit |
6c4009 |
@chapter Low-Level Terminal Interface
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
This chapter describes functions that are specific to terminal devices.
|
|
Packit |
6c4009 |
You can use these functions to do things like turn off input echoing;
|
|
Packit |
6c4009 |
set serial line characteristics such as line speed and flow control; and
|
|
Packit |
6c4009 |
change which characters are used for end-of-file, command-line editing,
|
|
Packit |
6c4009 |
sending signals, and similar control functions.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
Most of the functions in this chapter operate on file descriptors.
|
|
Packit |
6c4009 |
@xref{Low-Level I/O}, for more information about what a file
|
|
Packit |
6c4009 |
descriptor is and how to open a file descriptor for a terminal device.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@menu
|
|
Packit |
6c4009 |
* Is It a Terminal:: How to determine if a file is a terminal
|
|
Packit |
6c4009 |
device, and what its name is.
|
|
Packit |
6c4009 |
* I/O Queues:: About flow control and typeahead.
|
|
Packit |
6c4009 |
* Canonical or Not:: Two basic styles of input processing.
|
|
Packit |
6c4009 |
* Terminal Modes:: How to examine and modify flags controlling
|
|
Packit |
6c4009 |
details of terminal I/O: echoing,
|
|
Packit |
6c4009 |
signals, editing. Posix.
|
|
Packit |
6c4009 |
* BSD Terminal Modes:: BSD compatible terminal mode setting
|
|
Packit |
6c4009 |
* Line Control:: Sending break sequences, clearing
|
|
Packit |
6c4009 |
terminal buffers @dots{}
|
|
Packit |
6c4009 |
* Noncanon Example:: How to read single characters without echo.
|
|
Packit |
6c4009 |
* getpass:: Prompting the user for a passphrase.
|
|
Packit |
6c4009 |
* Pseudo-Terminals:: How to open a pseudo-terminal.
|
|
Packit |
6c4009 |
@end menu
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@node Is It a Terminal
|
|
Packit |
6c4009 |
@section Identifying Terminals
|
|
Packit |
6c4009 |
@cindex terminal identification
|
|
Packit |
6c4009 |
@cindex identifying terminals
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
The functions described in this chapter only work on files that
|
|
Packit |
6c4009 |
correspond to terminal devices. You can find out whether a file
|
|
Packit |
6c4009 |
descriptor is associated with a terminal by using the @code{isatty}
|
|
Packit |
6c4009 |
function.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@pindex unistd.h
|
|
Packit |
6c4009 |
Prototypes for the functions in this section are declared in the header
|
|
Packit |
6c4009 |
file @file{unistd.h}.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@deftypefun int isatty (int @var{filedes})
|
|
Packit |
6c4009 |
@standards{POSIX.1, unistd.h}
|
|
Packit |
6c4009 |
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
|
|
Packit |
6c4009 |
@c isatty ok
|
|
Packit |
6c4009 |
@c tcgetattr dup ok
|
|
Packit |
6c4009 |
This function returns @code{1} if @var{filedes} is a file descriptor
|
|
Packit |
6c4009 |
associated with an open terminal device, and @math{0} otherwise.
|
|
Packit |
6c4009 |
@end deftypefun
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
If a file descriptor is associated with a terminal, you can get its
|
|
Packit |
6c4009 |
associated file name using the @code{ttyname} function. See also the
|
|
Packit |
6c4009 |
@code{ctermid} function, described in @ref{Identifying the Terminal}.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@deftypefun {char *} ttyname (int @var{filedes})
|
|
Packit |
6c4009 |
@standards{POSIX.1, unistd.h}
|
|
Packit |
6c4009 |
@safety{@prelim{}@mtunsafe{@mtasurace{:ttyname}}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsfd{} @acsmem{}}}
|
|
Packit |
6c4009 |
@c ttyname @mtasurace:ttyname @ascuheap @asulock @aculock @acsmem @acsfd
|
|
Packit |
6c4009 |
@c isatty dup ok
|
|
Packit |
6c4009 |
@c fstat dup ok
|
|
Packit |
6c4009 |
@c memcpy dup ok
|
|
Packit |
6c4009 |
@c getttyname @mtasurace:ttyname @ascuheap @asulock @aculock @acsmem @acsfd
|
|
Packit |
6c4009 |
@c opendir @ascuheap @acsmem @acsfd
|
|
Packit |
6c4009 |
@c readdir ok [protected by exclusive access]
|
|
Packit |
6c4009 |
@c strcmp dup ok
|
|
Packit |
6c4009 |
@c free dup @asulock @aculock @acsfd @acsmem
|
|
Packit |
6c4009 |
@c malloc dup @asulock @aculock @acsfd @acsmem
|
|
Packit |
6c4009 |
@c closedir @ascuheap @acsmem @acsfd
|
|
Packit |
6c4009 |
@c mempcpy dup ok
|
|
Packit |
6c4009 |
@c stat dup ok
|
|
Packit |
6c4009 |
If the file descriptor @var{filedes} is associated with a terminal
|
|
Packit |
6c4009 |
device, the @code{ttyname} function returns a pointer to a
|
|
Packit |
6c4009 |
statically-allocated, null-terminated string containing the file name of
|
|
Packit |
6c4009 |
the terminal file. The value is a null pointer if the file descriptor
|
|
Packit |
6c4009 |
isn't associated with a terminal, or the file name cannot be determined.
|
|
Packit |
6c4009 |
@end deftypefun
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@deftypefun int ttyname_r (int @var{filedes}, char *@var{buf}, size_t @var{len})
|
|
Packit |
6c4009 |
@standards{POSIX.1, unistd.h}
|
|
Packit |
6c4009 |
@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{} @acsfd{}}}
|
|
Packit |
6c4009 |
@c ttyname_r @ascuheap @acsmem @acsfd
|
|
Packit |
6c4009 |
@c isatty dup ok
|
|
Packit |
6c4009 |
@c fstat dup ok
|
|
Packit |
6c4009 |
@c memcpy dup ok
|
|
Packit |
6c4009 |
@c getttyname_r @ascuheap @acsmem @acsfd
|
|
Packit |
6c4009 |
@c opendir @ascuheap @acsmem @acsfd
|
|
Packit |
6c4009 |
@c readdir ok [protected by exclusive access]
|
|
Packit |
6c4009 |
@c strcmp dup ok
|
|
Packit |
6c4009 |
@c closedir @ascuheap @acsmem @acsfd
|
|
Packit |
6c4009 |
@c stpncpy dup ok
|
|
Packit |
6c4009 |
@c stat dup ok
|
|
Packit |
6c4009 |
The @code{ttyname_r} function is similar to the @code{ttyname} function
|
|
Packit |
6c4009 |
except that it places its result into the user-specified buffer starting
|
|
Packit |
6c4009 |
at @var{buf} with length @var{len}.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
The normal return value from @code{ttyname_r} is @math{0}. Otherwise an
|
|
Packit |
6c4009 |
error number is returned to indicate the error. The following
|
|
Packit |
6c4009 |
@code{errno} error conditions are defined for this function:
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@table @code
|
|
Packit |
6c4009 |
@item EBADF
|
|
Packit |
6c4009 |
The @var{filedes} argument is not a valid file descriptor.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@item ENOTTY
|
|
Packit |
6c4009 |
The @var{filedes} is not associated with a terminal.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@item ERANGE
|
|
Packit |
6c4009 |
The buffer length @var{len} is too small to store the string to be
|
|
Packit |
6c4009 |
returned.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@item ENODEV
|
|
Packit |
6c4009 |
The @var{filedes} is associated with a terminal device that is a slave
|
|
Packit |
6c4009 |
pseudo-terminal, but the file name associated with that device could
|
|
Packit |
6c4009 |
not be determined. This is a GNU extension.
|
|
Packit |
6c4009 |
@end table
|
|
Packit |
6c4009 |
@end deftypefun
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@node I/O Queues
|
|
Packit |
6c4009 |
@section I/O Queues
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
Many of the remaining functions in this section refer to the input and
|
|
Packit |
6c4009 |
output queues of a terminal device. These queues implement a form of
|
|
Packit |
6c4009 |
buffering @emph{within the kernel} independent of the buffering
|
|
Packit |
6c4009 |
implemented by I/O streams (@pxref{I/O on Streams}).
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@cindex terminal input queue
|
|
Packit |
6c4009 |
@cindex typeahead buffer
|
|
Packit |
6c4009 |
The @dfn{terminal input queue} is also sometimes referred to as its
|
|
Packit |
6c4009 |
@dfn{typeahead buffer}. It holds the characters that have been received
|
|
Packit |
6c4009 |
from the terminal but not yet read by any process.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
The size of the input queue is described by the @code{MAX_INPUT} and
|
|
Packit |
6c4009 |
@w{@code{_POSIX_MAX_INPUT}} parameters; see @ref{Limits for Files}. You
|
|
Packit |
6c4009 |
are guaranteed a queue size of at least @code{MAX_INPUT}, but the queue
|
|
Packit |
6c4009 |
might be larger, and might even dynamically change size. If input flow
|
|
Packit |
6c4009 |
control is enabled by setting the @code{IXOFF} input mode bit
|
|
Packit |
6c4009 |
(@pxref{Input Modes}), the terminal driver transmits STOP and START
|
|
Packit |
6c4009 |
characters to the terminal when necessary to prevent the queue from
|
|
Packit |
6c4009 |
overflowing. Otherwise, input may be lost if it comes in too fast from
|
|
Packit |
6c4009 |
the terminal. In canonical mode, all input stays in the queue until a
|
|
Packit |
6c4009 |
newline character is received, so the terminal input queue can fill up
|
|
Packit |
6c4009 |
when you type a very long line. @xref{Canonical or Not}.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@cindex terminal output queue
|
|
Packit |
6c4009 |
The @dfn{terminal output queue} is like the input queue, but for output;
|
|
Packit |
6c4009 |
it contains characters that have been written by processes, but not yet
|
|
Packit |
6c4009 |
transmitted to the terminal. If output flow control is enabled by
|
|
Packit |
6c4009 |
setting the @code{IXON} input mode bit (@pxref{Input Modes}), the
|
|
Packit |
6c4009 |
terminal driver obeys START and STOP characters sent by the terminal to
|
|
Packit |
6c4009 |
stop and restart transmission of output.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@dfn{Clearing} the terminal input queue means discarding any characters
|
|
Packit |
6c4009 |
that have been received but not yet read. Similarly, clearing the
|
|
Packit |
6c4009 |
terminal output queue means discarding any characters that have been
|
|
Packit |
6c4009 |
written but not yet transmitted.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@node Canonical or Not
|
|
Packit |
6c4009 |
@section Two Styles of Input: Canonical or Not
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
POSIX systems support two basic modes of input: canonical and
|
|
Packit |
6c4009 |
noncanonical.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@cindex canonical input processing
|
|
Packit |
6c4009 |
In @dfn{canonical input processing} mode, terminal input is processed in
|
|
Packit |
6c4009 |
lines terminated by newline (@code{'\n'}), EOF, or EOL characters. No
|
|
Packit |
6c4009 |
input can be read until an entire line has been typed by the user, and
|
|
Packit |
6c4009 |
the @code{read} function (@pxref{I/O Primitives}) returns at most a
|
|
Packit |
6c4009 |
single line of input, no matter how many bytes are requested.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
In canonical input mode, the operating system provides input editing
|
|
Packit |
6c4009 |
facilities: some characters are interpreted specially to perform editing
|
|
Packit |
6c4009 |
operations within the current line of text, such as ERASE and KILL.
|
|
Packit |
6c4009 |
@xref{Editing Characters}.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
The constants @code{_POSIX_MAX_CANON} and @code{MAX_CANON} parameterize
|
|
Packit |
6c4009 |
the maximum number of bytes which may appear in a single line of
|
|
Packit |
6c4009 |
canonical input. @xref{Limits for Files}. You are guaranteed a maximum
|
|
Packit |
6c4009 |
line length of at least @code{MAX_CANON} bytes, but the maximum might be
|
|
Packit |
6c4009 |
larger, and might even dynamically change size.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@cindex noncanonical input processing
|
|
Packit |
6c4009 |
In @dfn{noncanonical input processing} mode, characters are not grouped
|
|
Packit |
6c4009 |
into lines, and ERASE and KILL processing is not performed. The
|
|
Packit |
6c4009 |
granularity with which bytes are read in noncanonical input mode is
|
|
Packit |
6c4009 |
controlled by the MIN and TIME settings. @xref{Noncanonical Input}.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
Most programs use canonical input mode, because this gives the user a
|
|
Packit |
6c4009 |
way to edit input line by line. The usual reason to use noncanonical
|
|
Packit |
6c4009 |
mode is when the program accepts single-character commands or provides
|
|
Packit |
6c4009 |
its own editing facilities.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
The choice of canonical or noncanonical input is controlled by the
|
|
Packit |
6c4009 |
@code{ICANON} flag in the @code{c_lflag} member of @code{struct termios}.
|
|
Packit |
6c4009 |
@xref{Local Modes}.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@node Terminal Modes
|
|
Packit |
6c4009 |
@section Terminal Modes
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@pindex termios.h
|
|
Packit |
6c4009 |
This section describes the various terminal attributes that control how
|
|
Packit |
6c4009 |
input and output are done. The functions, data structures, and symbolic
|
|
Packit |
6c4009 |
constants are all declared in the header file @file{termios.h}.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
Don't confuse terminal attributes with file attributes. A device special
|
|
Packit |
6c4009 |
file which is associated with a terminal has file attributes as described
|
|
Packit |
6c4009 |
in @ref{File Attributes}. These are unrelated to the attributes of the
|
|
Packit |
6c4009 |
terminal device itself, which are discussed in this section.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@menu
|
|
Packit |
6c4009 |
* Mode Data Types:: The data type @code{struct termios} and
|
|
Packit |
6c4009 |
related types.
|
|
Packit |
6c4009 |
* Mode Functions:: Functions to read and set the terminal
|
|
Packit |
6c4009 |
attributes.
|
|
Packit |
6c4009 |
* Setting Modes:: The right way to set terminal attributes
|
|
Packit |
6c4009 |
reliably.
|
|
Packit |
6c4009 |
* Input Modes:: Flags controlling low-level input handling.
|
|
Packit |
6c4009 |
* Output Modes:: Flags controlling low-level output handling.
|
|
Packit |
6c4009 |
* Control Modes:: Flags controlling serial port behavior.
|
|
Packit |
6c4009 |
* Local Modes:: Flags controlling high-level input handling.
|
|
Packit |
6c4009 |
* Line Speed:: How to read and set the terminal line speed.
|
|
Packit |
6c4009 |
* Special Characters:: Characters that have special effects,
|
|
Packit |
6c4009 |
and how to change them.
|
|
Packit |
6c4009 |
* Noncanonical Input:: Controlling how long to wait for input.
|
|
Packit |
6c4009 |
@end menu
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@node Mode Data Types
|
|
Packit |
6c4009 |
@subsection Terminal Mode Data Types
|
|
Packit |
6c4009 |
@cindex terminal mode data types
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
The entire collection of attributes of a terminal is stored in a
|
|
Packit |
6c4009 |
structure of type @code{struct termios}. This structure is used
|
|
Packit |
6c4009 |
with the functions @code{tcgetattr} and @code{tcsetattr} to read
|
|
Packit |
6c4009 |
and set the attributes.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@deftp {Data Type} {struct termios}
|
|
Packit |
6c4009 |
@standards{POSIX.1, termios.h}
|
|
Packit |
6c4009 |
A @code{struct termios} records all the I/O attributes of a terminal. The
|
|
Packit |
6c4009 |
structure includes at least the following members:
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@table @code
|
|
Packit |
6c4009 |
@item tcflag_t c_iflag
|
|
Packit |
6c4009 |
A bit mask specifying flags for input modes; see @ref{Input Modes}.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@item tcflag_t c_oflag
|
|
Packit |
6c4009 |
A bit mask specifying flags for output modes; see @ref{Output Modes}.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@item tcflag_t c_cflag
|
|
Packit |
6c4009 |
A bit mask specifying flags for control modes; see @ref{Control Modes}.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@item tcflag_t c_lflag
|
|
Packit |
6c4009 |
A bit mask specifying flags for local modes; see @ref{Local Modes}.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@item cc_t c_cc[NCCS]
|
|
Packit |
6c4009 |
An array specifying which characters are associated with various
|
|
Packit |
6c4009 |
control functions; see @ref{Special Characters}.
|
|
Packit |
6c4009 |
@end table
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
The @code{struct termios} structure also contains members which
|
|
Packit |
6c4009 |
encode input and output transmission speeds, but the representation is
|
|
Packit |
6c4009 |
not specified. @xref{Line Speed}, for how to examine and store the
|
|
Packit |
6c4009 |
speed values.
|
|
Packit |
6c4009 |
@end deftp
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
The following sections describe the details of the members of the
|
|
Packit |
6c4009 |
@code{struct termios} structure.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@deftp {Data Type} tcflag_t
|
|
Packit |
6c4009 |
@standards{POSIX.1, termios.h}
|
|
Packit |
6c4009 |
This is an unsigned integer type used to represent the various
|
|
Packit |
6c4009 |
bit masks for terminal flags.
|
|
Packit |
6c4009 |
@end deftp
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@deftp {Data Type} cc_t
|
|
Packit |
6c4009 |
@standards{POSIX.1, termios.h}
|
|
Packit |
6c4009 |
This is an unsigned integer type used to represent characters associated
|
|
Packit |
6c4009 |
with various terminal control functions.
|
|
Packit |
6c4009 |
@end deftp
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@deftypevr Macro int NCCS
|
|
Packit |
6c4009 |
@standards{POSIX.1, termios.h}
|
|
Packit |
6c4009 |
The value of this macro is the number of elements in the @code{c_cc}
|
|
Packit |
6c4009 |
array.
|
|
Packit |
6c4009 |
@end deftypevr
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@node Mode Functions
|
|
Packit |
6c4009 |
@subsection Terminal Mode Functions
|
|
Packit |
6c4009 |
@cindex terminal mode functions
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@deftypefun int tcgetattr (int @var{filedes}, struct termios *@var{termios-p})
|
|
Packit |
6c4009 |
@standards{POSIX.1, termios.h}
|
|
Packit |
6c4009 |
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
|
|
Packit |
6c4009 |
@c Converting the kernel-returned termios data structure to the userland
|
|
Packit |
6c4009 |
@c format does not ensure atomic or consistent writing.
|
|
Packit |
6c4009 |
This function is used to examine the attributes of the terminal
|
|
Packit |
6c4009 |
device with file descriptor @var{filedes}. The attributes are returned
|
|
Packit |
6c4009 |
in the structure that @var{termios-p} points to.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
If successful, @code{tcgetattr} returns @math{0}. A return value of @math{-1}
|
|
Packit |
6c4009 |
indicates an error. The following @code{errno} error conditions are
|
|
Packit |
6c4009 |
defined for this function:
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@table @code
|
|
Packit |
6c4009 |
@item EBADF
|
|
Packit |
6c4009 |
The @var{filedes} argument is not a valid file descriptor.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@item ENOTTY
|
|
Packit |
6c4009 |
The @var{filedes} is not associated with a terminal.
|
|
Packit |
6c4009 |
@end table
|
|
Packit |
6c4009 |
@end deftypefun
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@deftypefun int tcsetattr (int @var{filedes}, int @var{when}, const struct termios *@var{termios-p})
|
|
Packit |
6c4009 |
@standards{POSIX.1, termios.h}
|
|
Packit |
6c4009 |
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
|
|
Packit |
6c4009 |
@c Converting the incoming termios data structure to the kernel format
|
|
Packit |
6c4009 |
@c does not ensure atomic or consistent reading.
|
|
Packit |
6c4009 |
This function sets the attributes of the terminal device with file
|
|
Packit |
6c4009 |
descriptor @var{filedes}. The new attributes are taken from the
|
|
Packit |
6c4009 |
structure that @var{termios-p} points to.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
The @var{when} argument specifies how to deal with input and output
|
|
Packit |
6c4009 |
already queued. It can be one of the following values:
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@vtable @code
|
|
Packit |
6c4009 |
@item TCSANOW
|
|
Packit |
6c4009 |
@standards{POSIX.1, termios.h}
|
|
Packit |
6c4009 |
Make the change immediately.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@item TCSADRAIN
|
|
Packit |
6c4009 |
@standards{POSIX.1, termios.h}
|
|
Packit |
6c4009 |
Make the change after waiting until all queued output has been written.
|
|
Packit |
6c4009 |
You should usually use this option when changing parameters that affect
|
|
Packit |
6c4009 |
output.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@item TCSAFLUSH
|
|
Packit |
6c4009 |
@standards{POSIX.1, termios.h}
|
|
Packit |
6c4009 |
This is like @code{TCSADRAIN}, but also discards any queued input.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@item TCSASOFT
|
|
Packit |
6c4009 |
@standards{BSD, termios.h}
|
|
Packit |
6c4009 |
This is a flag bit that you can add to any of the above alternatives.
|
|
Packit |
6c4009 |
Its meaning is to inhibit alteration of the state of the terminal
|
|
Packit |
6c4009 |
hardware. It is a BSD extension; it is only supported on BSD systems
|
|
Packit |
6c4009 |
and @gnuhurdsystems{}.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
Using @code{TCSASOFT} is exactly the same as setting the @code{CIGNORE}
|
|
Packit |
6c4009 |
bit in the @code{c_cflag} member of the structure @var{termios-p} points
|
|
Packit |
6c4009 |
to. @xref{Control Modes}, for a description of @code{CIGNORE}.
|
|
Packit |
6c4009 |
@end vtable
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
If this function is called from a background process on its controlling
|
|
Packit |
6c4009 |
terminal, normally all processes in the process group are sent a
|
|
Packit |
6c4009 |
@code{SIGTTOU} signal, in the same way as if the process were trying to
|
|
Packit |
6c4009 |
write to the terminal. The exception is if the calling process itself
|
|
Packit |
6c4009 |
is ignoring or blocking @code{SIGTTOU} signals, in which case the
|
|
Packit |
6c4009 |
operation is performed and no signal is sent. @xref{Job Control}.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
If successful, @code{tcsetattr} returns @math{0}. A return value of
|
|
Packit |
6c4009 |
@math{-1} indicates an error. The following @code{errno} error
|
|
Packit |
6c4009 |
conditions are defined for this function:
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@table @code
|
|
Packit |
6c4009 |
@item EBADF
|
|
Packit |
6c4009 |
The @var{filedes} argument is not a valid file descriptor.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@item ENOTTY
|
|
Packit |
6c4009 |
The @var{filedes} is not associated with a terminal.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@item EINVAL
|
|
Packit |
6c4009 |
Either the value of the @code{when} argument is not valid, or there is
|
|
Packit |
6c4009 |
something wrong with the data in the @var{termios-p} argument.
|
|
Packit |
6c4009 |
@end table
|
|
Packit |
6c4009 |
@end deftypefun
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
Although @code{tcgetattr} and @code{tcsetattr} specify the terminal
|
|
Packit |
6c4009 |
device with a file descriptor, the attributes are those of the terminal
|
|
Packit |
6c4009 |
device itself and not of the file descriptor. This means that the
|
|
Packit |
6c4009 |
effects of changing terminal attributes are persistent; if another
|
|
Packit |
6c4009 |
process opens the terminal file later on, it will see the changed
|
|
Packit |
6c4009 |
attributes even though it doesn't have anything to do with the open file
|
|
Packit |
6c4009 |
descriptor you originally specified in changing the attributes.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
Similarly, if a single process has multiple or duplicated file
|
|
Packit |
6c4009 |
descriptors for the same terminal device, changing the terminal
|
|
Packit |
6c4009 |
attributes affects input and output to all of these file
|
|
Packit |
6c4009 |
descriptors. This means, for example, that you can't open one file
|
|
Packit |
6c4009 |
descriptor or stream to read from a terminal in the normal
|
|
Packit |
6c4009 |
line-buffered, echoed mode; and simultaneously have another file
|
|
Packit |
6c4009 |
descriptor for the same terminal that you use to read from it in
|
|
Packit |
6c4009 |
single-character, non-echoed mode. Instead, you have to explicitly
|
|
Packit |
6c4009 |
switch the terminal back and forth between the two modes.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@node Setting Modes
|
|
Packit |
6c4009 |
@subsection Setting Terminal Modes Properly
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
When you set terminal modes, you should call @code{tcgetattr} first to
|
|
Packit |
6c4009 |
get the current modes of the particular terminal device, modify only
|
|
Packit |
6c4009 |
those modes that you are really interested in, and store the result with
|
|
Packit |
6c4009 |
@code{tcsetattr}.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
It's a bad idea to simply initialize a @code{struct termios} structure
|
|
Packit |
6c4009 |
to a chosen set of attributes and pass it directly to @code{tcsetattr}.
|
|
Packit |
6c4009 |
Your program may be run years from now, on systems that support members
|
|
Packit |
6c4009 |
not documented in this manual. The way to avoid setting these members
|
|
Packit |
6c4009 |
to unreasonable values is to avoid changing them.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
What's more, different terminal devices may require different mode
|
|
Packit |
6c4009 |
settings in order to function properly. So you should avoid blindly
|
|
Packit |
6c4009 |
copying attributes from one terminal device to another.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
When a member contains a collection of independent flags, as the
|
|
Packit |
6c4009 |
@code{c_iflag}, @code{c_oflag} and @code{c_cflag} members do, even
|
|
Packit |
6c4009 |
setting the entire member is a bad idea, because particular operating
|
|
Packit |
6c4009 |
systems have their own flags. Instead, you should start with the
|
|
Packit |
6c4009 |
current value of the member and alter only the flags whose values matter
|
|
Packit |
6c4009 |
in your program, leaving any other flags unchanged.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
Here is an example of how to set one flag (@code{ISTRIP}) in the
|
|
Packit |
6c4009 |
@code{struct termios} structure while properly preserving all the other
|
|
Packit |
6c4009 |
data in the structure:
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@smallexample
|
|
Packit |
6c4009 |
@group
|
|
Packit |
6c4009 |
int
|
|
Packit |
6c4009 |
set_istrip (int desc, int value)
|
|
Packit |
6c4009 |
@{
|
|
Packit |
6c4009 |
struct termios settings;
|
|
Packit |
6c4009 |
int result;
|
|
Packit |
6c4009 |
@end group
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@group
|
|
Packit |
6c4009 |
result = tcgetattr (desc, &settings);
|
|
Packit |
6c4009 |
if (result < 0)
|
|
Packit |
6c4009 |
@{
|
|
Packit |
6c4009 |
perror ("error in tcgetattr");
|
|
Packit |
6c4009 |
return 0;
|
|
Packit |
6c4009 |
@}
|
|
Packit |
6c4009 |
@end group
|
|
Packit |
6c4009 |
@group
|
|
Packit |
6c4009 |
settings.c_iflag &= ~ISTRIP;
|
|
Packit |
6c4009 |
if (value)
|
|
Packit |
6c4009 |
settings.c_iflag |= ISTRIP;
|
|
Packit |
6c4009 |
@end group
|
|
Packit |
6c4009 |
@group
|
|
Packit |
6c4009 |
result = tcsetattr (desc, TCSANOW, &settings);
|
|
Packit |
6c4009 |
if (result < 0)
|
|
Packit |
6c4009 |
@{
|
|
Packit |
6c4009 |
perror ("error in tcsetattr");
|
|
Packit |
6c4009 |
return 0;
|
|
Packit |
6c4009 |
@}
|
|
Packit |
6c4009 |
return 1;
|
|
Packit |
6c4009 |
@}
|
|
Packit |
6c4009 |
@end group
|
|
Packit |
6c4009 |
@end smallexample
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@node Input Modes
|
|
Packit |
6c4009 |
@subsection Input Modes
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
This section describes the terminal attribute flags that control
|
|
Packit |
6c4009 |
fairly low-level aspects of input processing: handling of parity errors,
|
|
Packit |
6c4009 |
break signals, flow control, and @key{RET} and @key{LFD} characters.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
All of these flags are bits in the @code{c_iflag} member of the
|
|
Packit |
6c4009 |
@code{struct termios} structure. The member is an integer, and you
|
|
Packit |
6c4009 |
change flags using the operators @code{&}, @code{|} and @code{^}. Don't
|
|
Packit |
6c4009 |
try to specify the entire value for @code{c_iflag}---instead, change
|
|
Packit |
6c4009 |
only specific flags and leave the rest untouched (@pxref{Setting
|
|
Packit |
6c4009 |
Modes}).
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@deftypevr Macro tcflag_t INPCK
|
|
Packit |
6c4009 |
@standards{POSIX.1, termios.h}
|
|
Packit |
6c4009 |
@cindex parity checking
|
|
Packit |
6c4009 |
If this bit is set, input parity checking is enabled. If it is not set,
|
|
Packit |
6c4009 |
no checking at all is done for parity errors on input; the
|
|
Packit |
6c4009 |
characters are simply passed through to the application.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
Parity checking on input processing is independent of whether parity
|
|
Packit |
6c4009 |
detection and generation on the underlying terminal hardware is enabled;
|
|
Packit |
6c4009 |
see @ref{Control Modes}. For example, you could clear the @code{INPCK}
|
|
Packit |
6c4009 |
input mode flag and set the @code{PARENB} control mode flag to ignore
|
|
Packit |
6c4009 |
parity errors on input, but still generate parity on output.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
If this bit is set, what happens when a parity error is detected depends
|
|
Packit |
6c4009 |
on whether the @code{IGNPAR} or @code{PARMRK} bits are set. If neither
|
|
Packit |
6c4009 |
of these bits are set, a byte with a parity error is passed to the
|
|
Packit |
6c4009 |
application as a @code{'\0'} character.
|
|
Packit |
6c4009 |
@end deftypevr
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@deftypevr Macro tcflag_t IGNPAR
|
|
Packit |
6c4009 |
@standards{POSIX.1, termios.h}
|
|
Packit |
6c4009 |
If this bit is set, any byte with a framing or parity error is ignored.
|
|
Packit |
6c4009 |
This is only useful if @code{INPCK} is also set.
|
|
Packit |
6c4009 |
@end deftypevr
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@deftypevr Macro tcflag_t PARMRK
|
|
Packit |
6c4009 |
@standards{POSIX.1, termios.h}
|
|
Packit |
6c4009 |
If this bit is set, input bytes with parity or framing errors are marked
|
|
Packit |
6c4009 |
when passed to the program. This bit is meaningful only when
|
|
Packit |
6c4009 |
@code{INPCK} is set and @code{IGNPAR} is not set.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
The way erroneous bytes are marked is with two preceding bytes,
|
|
Packit |
6c4009 |
@code{377} and @code{0}. Thus, the program actually reads three bytes
|
|
Packit |
6c4009 |
for one erroneous byte received from the terminal.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
If a valid byte has the value @code{0377}, and @code{ISTRIP} (see below)
|
|
Packit |
6c4009 |
is not set, the program might confuse it with the prefix that marks a
|
|
Packit |
6c4009 |
parity error. So a valid byte @code{0377} is passed to the program as
|
|
Packit |
6c4009 |
two bytes, @code{0377} @code{0377}, in this case.
|
|
Packit |
6c4009 |
@end deftypevr
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@deftypevr Macro tcflag_t ISTRIP
|
|
Packit |
6c4009 |
@standards{POSIX.1, termios.h}
|
|
Packit |
6c4009 |
If this bit is set, valid input bytes are stripped to seven bits;
|
|
Packit |
6c4009 |
otherwise, all eight bits are available for programs to read.
|
|
Packit |
6c4009 |
@end deftypevr
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@deftypevr Macro tcflag_t IGNBRK
|
|
Packit |
6c4009 |
@standards{POSIX.1, termios.h}
|
|
Packit |
6c4009 |
If this bit is set, break conditions are ignored.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@cindex break condition, detecting
|
|
Packit |
6c4009 |
A @dfn{break condition} is defined in the context of asynchronous
|
|
Packit |
6c4009 |
serial data transmission as a series of zero-value bits longer than a
|
|
Packit |
6c4009 |
single byte.
|
|
Packit |
6c4009 |
@end deftypevr
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@deftypevr Macro tcflag_t BRKINT
|
|
Packit |
6c4009 |
@standards{POSIX.1, termios.h}
|
|
Packit |
6c4009 |
If this bit is set and @code{IGNBRK} is not set, a break condition
|
|
Packit |
6c4009 |
clears the terminal input and output queues and raises a @code{SIGINT}
|
|
Packit |
6c4009 |
signal for the foreground process group associated with the terminal.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
If neither @code{BRKINT} nor @code{IGNBRK} are set, a break condition is
|
|
Packit |
6c4009 |
passed to the application as a single @code{'\0'} character if
|
|
Packit |
6c4009 |
@code{PARMRK} is not set, or otherwise as a three-character sequence
|
|
Packit |
6c4009 |
@code{'\377'}, @code{'\0'}, @code{'\0'}.
|
|
Packit |
6c4009 |
@end deftypevr
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@deftypevr Macro tcflag_t IGNCR
|
|
Packit |
6c4009 |
@standards{POSIX.1, termios.h}
|
|
Packit |
6c4009 |
If this bit is set, carriage return characters (@code{'\r'}) are
|
|
Packit |
6c4009 |
discarded on input. Discarding carriage return may be useful on
|
|
Packit |
6c4009 |
terminals that send both carriage return and linefeed when you type the
|
|
Packit |
6c4009 |
@key{RET} key.
|
|
Packit |
6c4009 |
@end deftypevr
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@deftypevr Macro tcflag_t ICRNL
|
|
Packit |
6c4009 |
@standards{POSIX.1, termios.h}
|
|
Packit |
6c4009 |
If this bit is set and @code{IGNCR} is not set, carriage return characters
|
|
Packit |
6c4009 |
(@code{'\r'}) received as input are passed to the application as newline
|
|
Packit |
6c4009 |
characters (@code{'\n'}).
|
|
Packit |
6c4009 |
@end deftypevr
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@deftypevr Macro tcflag_t INLCR
|
|
Packit |
6c4009 |
@standards{POSIX.1, termios.h}
|
|
Packit |
6c4009 |
If this bit is set, newline characters (@code{'\n'}) received as input
|
|
Packit |
6c4009 |
are passed to the application as carriage return characters (@code{'\r'}).
|
|
Packit |
6c4009 |
@end deftypevr
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@deftypevr Macro tcflag_t IXOFF
|
|
Packit |
6c4009 |
@standards{POSIX.1, termios.h}
|
|
Packit |
6c4009 |
If this bit is set, start/stop control on input is enabled. In other
|
|
Packit |
6c4009 |
words, the computer sends STOP and START characters as necessary to
|
|
Packit |
6c4009 |
prevent input from coming in faster than programs are reading it. The
|
|
Packit |
6c4009 |
idea is that the actual terminal hardware that is generating the input
|
|
Packit |
6c4009 |
data responds to a STOP character by suspending transmission, and to a
|
|
Packit |
6c4009 |
START character by resuming transmission. @xref{Start/Stop Characters}.
|
|
Packit |
6c4009 |
@end deftypevr
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@deftypevr Macro tcflag_t IXON
|
|
Packit |
6c4009 |
@standards{POSIX.1, termios.h}
|
|
Packit |
6c4009 |
If this bit is set, start/stop control on output is enabled. In other
|
|
Packit |
6c4009 |
words, if the computer receives a STOP character, it suspends output
|
|
Packit |
6c4009 |
until a START character is received. In this case, the STOP and START
|
|
Packit |
6c4009 |
characters are never passed to the application program. If this bit is
|
|
Packit |
6c4009 |
not set, then START and STOP can be read as ordinary characters.
|
|
Packit |
6c4009 |
@xref{Start/Stop Characters}.
|
|
Packit |
6c4009 |
@c !!! mention this interferes with using C-s and C-q for programs like emacs
|
|
Packit |
6c4009 |
@end deftypevr
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@deftypevr Macro tcflag_t IXANY
|
|
Packit |
6c4009 |
@standards{BSD, termios.h}
|
|
Packit |
6c4009 |
If this bit is set, any input character restarts output when output has
|
|
Packit |
6c4009 |
been suspended with the STOP character. Otherwise, only the START
|
|
Packit |
6c4009 |
character restarts output.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
This is a BSD extension; it exists only on BSD systems and
|
|
Packit |
6c4009 |
@gnulinuxhurdsystems{}.
|
|
Packit |
6c4009 |
@end deftypevr
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@deftypevr Macro tcflag_t IMAXBEL
|
|
Packit |
6c4009 |
@standards{BSD, termios.h}
|
|
Packit |
6c4009 |
If this bit is set, then filling up the terminal input buffer sends a
|
|
Packit |
6c4009 |
BEL character (code @code{007}) to the terminal to ring the bell.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
This is a BSD extension.
|
|
Packit |
6c4009 |
@end deftypevr
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@node Output Modes
|
|
Packit |
6c4009 |
@subsection Output Modes
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
This section describes the terminal flags and fields that control how
|
|
Packit |
6c4009 |
output characters are translated and padded for display. All of these
|
|
Packit |
6c4009 |
are contained in the @code{c_oflag} member of the @w{@code{struct termios}}
|
|
Packit |
6c4009 |
structure.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
The @code{c_oflag} member itself is an integer, and you change the flags
|
|
Packit |
6c4009 |
and fields using the operators @code{&}, @code{|}, and @code{^}. Don't
|
|
Packit |
6c4009 |
try to specify the entire value for @code{c_oflag}---instead, change
|
|
Packit |
6c4009 |
only specific flags and leave the rest untouched (@pxref{Setting
|
|
Packit |
6c4009 |
Modes}).
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@deftypevr Macro tcflag_t OPOST
|
|
Packit |
6c4009 |
@standards{POSIX.1, termios.h}
|
|
Packit |
6c4009 |
If this bit is set, output data is processed in some unspecified way so
|
|
Packit |
6c4009 |
that it is displayed appropriately on the terminal device. This
|
|
Packit |
6c4009 |
typically includes mapping newline characters (@code{'\n'}) onto
|
|
Packit |
6c4009 |
carriage return and linefeed pairs.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
If this bit isn't set, the characters are transmitted as-is.
|
|
Packit |
6c4009 |
@end deftypevr
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
The following three bits are effective only if @code{OPOST} is set.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@deftypevr Macro tcflag_t ONLCR
|
|
Packit |
6c4009 |
@standards{POSIX.1, termios.h}
|
|
Packit |
6c4009 |
If this bit is set, convert the newline character on output into a pair
|
|
Packit |
6c4009 |
of characters, carriage return followed by linefeed.
|
|
Packit |
6c4009 |
@end deftypevr
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@deftypevr Macro tcflag_t OXTABS
|
|
Packit |
6c4009 |
@standards{BSD, termios.h (optional)}
|
|
Packit |
6c4009 |
If this bit is set, convert tab characters on output into the appropriate
|
|
Packit |
6c4009 |
number of spaces to emulate a tab stop every eight columns. This bit
|
|
Packit |
6c4009 |
exists only on BSD systems and @gnuhurdsystems{}; on
|
|
Packit |
6c4009 |
@gnulinuxsystems{} it is available as @code{XTABS}.
|
|
Packit |
6c4009 |
@end deftypevr
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@deftypevr Macro tcflag_t ONOEOT
|
|
Packit |
6c4009 |
@standards{BSD, termios.h (optional)}
|
|
Packit |
6c4009 |
If this bit is set, discard @kbd{C-d} characters (code @code{004}) on
|
|
Packit |
6c4009 |
output. These characters cause many dial-up terminals to disconnect.
|
|
Packit |
6c4009 |
This bit exists only on BSD systems and @gnuhurdsystems{}.
|
|
Packit |
6c4009 |
@end deftypevr
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@node Control Modes
|
|
Packit |
6c4009 |
@subsection Control Modes
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
This section describes the terminal flags and fields that control
|
|
Packit |
6c4009 |
parameters usually associated with asynchronous serial data
|
|
Packit |
6c4009 |
transmission. These flags may not make sense for other kinds of
|
|
Packit |
6c4009 |
terminal ports (such as a network connection pseudo-terminal). All of
|
|
Packit |
6c4009 |
these are contained in the @code{c_cflag} member of the @code{struct
|
|
Packit |
6c4009 |
termios} structure.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
The @code{c_cflag} member itself is an integer, and you change the flags
|
|
Packit |
6c4009 |
and fields using the operators @code{&}, @code{|}, and @code{^}. Don't
|
|
Packit |
6c4009 |
try to specify the entire value for @code{c_cflag}---instead, change
|
|
Packit |
6c4009 |
only specific flags and leave the rest untouched (@pxref{Setting
|
|
Packit |
6c4009 |
Modes}).
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@deftypevr Macro tcflag_t CLOCAL
|
|
Packit |
6c4009 |
@standards{POSIX.1, termios.h}
|
|
Packit |
6c4009 |
If this bit is set, it indicates that the terminal is connected
|
|
Packit |
6c4009 |
``locally'' and that the modem status lines (such as carrier detect)
|
|
Packit |
6c4009 |
should be ignored.
|
|
Packit |
6c4009 |
@cindex modem status lines
|
|
Packit |
6c4009 |
@cindex carrier detect
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
On many systems if this bit is not set and you call @code{open} without
|
|
Packit |
6c4009 |
the @code{O_NONBLOCK} flag set, @code{open} blocks until a modem
|
|
Packit |
6c4009 |
connection is established.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
If this bit is not set and a modem disconnect is detected, a
|
|
Packit |
6c4009 |
@code{SIGHUP} signal is sent to the controlling process group for the
|
|
Packit |
6c4009 |
terminal (if it has one). Normally, this causes the process to exit;
|
|
Packit |
6c4009 |
see @ref{Signal Handling}. Reading from the terminal after a disconnect
|
|
Packit |
6c4009 |
causes an end-of-file condition, and writing causes an @code{EIO} error
|
|
Packit |
6c4009 |
to be returned. The terminal device must be closed and reopened to
|
|
Packit |
6c4009 |
clear the condition.
|
|
Packit |
6c4009 |
@cindex modem disconnect
|
|
Packit |
6c4009 |
@end deftypevr
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@deftypevr Macro tcflag_t HUPCL
|
|
Packit |
6c4009 |
@standards{POSIX.1, termios.h}
|
|
Packit |
6c4009 |
If this bit is set, a modem disconnect is generated when all processes
|
|
Packit |
6c4009 |
that have the terminal device open have either closed the file or exited.
|
|
Packit |
6c4009 |
@end deftypevr
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@deftypevr Macro tcflag_t CREAD
|
|
Packit |
6c4009 |
@standards{POSIX.1, termios.h}
|
|
Packit |
6c4009 |
If this bit is set, input can be read from the terminal. Otherwise,
|
|
Packit |
6c4009 |
input is discarded when it arrives.
|
|
Packit |
6c4009 |
@end deftypevr
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@deftypevr Macro tcflag_t CSTOPB
|
|
Packit |
6c4009 |
@standards{POSIX.1, termios.h}
|
|
Packit |
6c4009 |
If this bit is set, two stop bits are used. Otherwise, only one stop bit
|
|
Packit |
6c4009 |
is used.
|
|
Packit |
6c4009 |
@end deftypevr
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@deftypevr Macro tcflag_t PARENB
|
|
Packit |
6c4009 |
@standards{POSIX.1, termios.h}
|
|
Packit |
6c4009 |
If this bit is set, generation and detection of a parity bit are enabled.
|
|
Packit |
6c4009 |
@xref{Input Modes}, for information on how input parity errors are handled.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
If this bit is not set, no parity bit is added to output characters, and
|
|
Packit |
6c4009 |
input characters are not checked for correct parity.
|
|
Packit |
6c4009 |
@end deftypevr
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@deftypevr Macro tcflag_t PARODD
|
|
Packit |
6c4009 |
@standards{POSIX.1, termios.h}
|
|
Packit |
6c4009 |
This bit is only useful if @code{PARENB} is set. If @code{PARODD} is set,
|
|
Packit |
6c4009 |
odd parity is used, otherwise even parity is used.
|
|
Packit |
6c4009 |
@end deftypevr
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
The control mode flags also includes a field for the number of bits per
|
|
Packit |
6c4009 |
character. You can use the @code{CSIZE} macro as a mask to extract the
|
|
Packit |
6c4009 |
value, like this: @code{settings.c_cflag & CSIZE}.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@deftypevr Macro tcflag_t CSIZE
|
|
Packit |
6c4009 |
@standards{POSIX.1, termios.h}
|
|
Packit |
6c4009 |
This is a mask for the number of bits per character.
|
|
Packit |
6c4009 |
@end deftypevr
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@deftypevr Macro tcflag_t CS5
|
|
Packit |
6c4009 |
@standards{POSIX.1, termios.h}
|
|
Packit |
6c4009 |
This specifies five bits per byte.
|
|
Packit |
6c4009 |
@end deftypevr
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@deftypevr Macro tcflag_t CS6
|
|
Packit |
6c4009 |
@standards{POSIX.1, termios.h}
|
|
Packit |
6c4009 |
This specifies six bits per byte.
|
|
Packit |
6c4009 |
@end deftypevr
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@deftypevr Macro tcflag_t CS7
|
|
Packit |
6c4009 |
@standards{POSIX.1, termios.h}
|
|
Packit |
6c4009 |
This specifies seven bits per byte.
|
|
Packit |
6c4009 |
@end deftypevr
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@deftypevr Macro tcflag_t CS8
|
|
Packit |
6c4009 |
@standards{POSIX.1, termios.h}
|
|
Packit |
6c4009 |
This specifies eight bits per byte.
|
|
Packit |
6c4009 |
@end deftypevr
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
The following four bits are BSD extensions; these exist only on BSD
|
|
Packit |
6c4009 |
systems and @gnuhurdsystems{}.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@deftypevr Macro tcflag_t CCTS_OFLOW
|
|
Packit |
6c4009 |
@standards{BSD, termios.h}
|
|
Packit |
6c4009 |
If this bit is set, enable flow control of output based on the CTS wire
|
|
Packit |
6c4009 |
(RS232 protocol).
|
|
Packit |
6c4009 |
@end deftypevr
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@deftypevr Macro tcflag_t CRTS_IFLOW
|
|
Packit |
6c4009 |
@standards{BSD, termios.h}
|
|
Packit |
6c4009 |
If this bit is set, enable flow control of input based on the RTS wire
|
|
Packit |
6c4009 |
(RS232 protocol).
|
|
Packit |
6c4009 |
@end deftypevr
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@deftypevr Macro tcflag_t MDMBUF
|
|
Packit |
6c4009 |
@standards{BSD, termios.h}
|
|
Packit |
6c4009 |
If this bit is set, enable carrier-based flow control of output.
|
|
Packit |
6c4009 |
@end deftypevr
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@deftypevr Macro tcflag_t CIGNORE
|
|
Packit |
6c4009 |
@standards{BSD, termios.h}
|
|
Packit |
6c4009 |
If this bit is set, it says to ignore the control modes and line speed
|
|
Packit |
6c4009 |
values entirely. This is only meaningful in a call to @code{tcsetattr}.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
The @code{c_cflag} member and the line speed values returned by
|
|
Packit |
6c4009 |
@code{cfgetispeed} and @code{cfgetospeed} will be unaffected by the
|
|
Packit |
6c4009 |
call. @code{CIGNORE} is useful if you want to set all the software
|
|
Packit |
6c4009 |
modes in the other members, but leave the hardware details in
|
|
Packit |
6c4009 |
@code{c_cflag} unchanged. (This is how the @code{TCSASOFT} flag to
|
|
Packit |
6c4009 |
@code{tcsettattr} works.)
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
This bit is never set in the structure filled in by @code{tcgetattr}.
|
|
Packit |
6c4009 |
@end deftypevr
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@node Local Modes
|
|
Packit |
6c4009 |
@subsection Local Modes
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
This section describes the flags for the @code{c_lflag} member of the
|
|
Packit |
6c4009 |
@code{struct termios} structure. These flags generally control
|
|
Packit |
6c4009 |
higher-level aspects of input processing than the input modes flags
|
|
Packit |
6c4009 |
described in @ref{Input Modes}, such as echoing, signals, and the choice
|
|
Packit |
6c4009 |
of canonical or noncanonical input.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
The @code{c_lflag} member itself is an integer, and you change the flags
|
|
Packit |
6c4009 |
and fields using the operators @code{&}, @code{|}, and @code{^}. Don't
|
|
Packit |
6c4009 |
try to specify the entire value for @code{c_lflag}---instead, change
|
|
Packit |
6c4009 |
only specific flags and leave the rest untouched (@pxref{Setting
|
|
Packit |
6c4009 |
Modes}).
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@deftypevr Macro tcflag_t ICANON
|
|
Packit |
6c4009 |
@standards{POSIX.1, termios.h}
|
|
Packit |
6c4009 |
This bit, if set, enables canonical input processing mode. Otherwise,
|
|
Packit |
6c4009 |
input is processed in noncanonical mode. @xref{Canonical or Not}.
|
|
Packit |
6c4009 |
@end deftypevr
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@deftypevr Macro tcflag_t ECHO
|
|
Packit |
6c4009 |
@standards{POSIX.1, termios.h}
|
|
Packit |
6c4009 |
If this bit is set, echoing of input characters back to the terminal
|
|
Packit |
6c4009 |
is enabled.
|
|
Packit |
6c4009 |
@cindex echo of terminal input
|
|
Packit |
6c4009 |
@end deftypevr
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@deftypevr Macro tcflag_t ECHOE
|
|
Packit |
6c4009 |
@standards{POSIX.1, termios.h}
|
|
Packit |
6c4009 |
If this bit is set, echoing indicates erasure of input with the ERASE
|
|
Packit |
6c4009 |
character by erasing the last character in the current line from the
|
|
Packit |
6c4009 |
screen. Otherwise, the character erased is re-echoed to show what has
|
|
Packit |
6c4009 |
happened (suitable for a printing terminal).
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
This bit only controls the display behavior; the @code{ICANON} bit by
|
|
Packit |
6c4009 |
itself controls actual recognition of the ERASE character and erasure of
|
|
Packit |
6c4009 |
input, without which @code{ECHOE} is simply irrelevant.
|
|
Packit |
6c4009 |
@end deftypevr
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@deftypevr Macro tcflag_t ECHOPRT
|
|
Packit |
6c4009 |
@standards{BSD, termios.h}
|
|
Packit |
6c4009 |
This bit, like @code{ECHOE}, enables display of the ERASE character in
|
|
Packit |
6c4009 |
a way that is geared to a hardcopy terminal. When you type the ERASE
|
|
Packit |
6c4009 |
character, a @samp{\} character is printed followed by the first
|
|
Packit |
6c4009 |
character erased. Typing the ERASE character again just prints the next
|
|
Packit |
6c4009 |
character erased. Then, the next time you type a normal character, a
|
|
Packit |
6c4009 |
@samp{/} character is printed before the character echoes.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
This is a BSD extension, and exists only in BSD systems and
|
|
Packit |
6c4009 |
@gnulinuxhurdsystems{}.
|
|
Packit |
6c4009 |
@end deftypevr
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@deftypevr Macro tcflag_t ECHOK
|
|
Packit |
6c4009 |
@standards{POSIX.1, termios.h}
|
|
Packit |
6c4009 |
This bit enables special display of the KILL character by moving to a
|
|
Packit |
6c4009 |
new line after echoing the KILL character normally. The behavior of
|
|
Packit |
6c4009 |
@code{ECHOKE} (below) is nicer to look at.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
If this bit is not set, the KILL character echoes just as it would if it
|
|
Packit |
6c4009 |
were not the KILL character. Then it is up to the user to remember that
|
|
Packit |
6c4009 |
the KILL character has erased the preceding input; there is no
|
|
Packit |
6c4009 |
indication of this on the screen.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
This bit only controls the display behavior; the @code{ICANON} bit by
|
|
Packit |
6c4009 |
itself controls actual recognition of the KILL character and erasure of
|
|
Packit |
6c4009 |
input, without which @code{ECHOK} is simply irrelevant.
|
|
Packit |
6c4009 |
@end deftypevr
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@deftypevr Macro tcflag_t ECHOKE
|
|
Packit |
6c4009 |
@standards{BSD, termios.h}
|
|
Packit |
6c4009 |
This bit is similar to @code{ECHOK}. It enables special display of the
|
|
Packit |
6c4009 |
KILL character by erasing on the screen the entire line that has been
|
|
Packit |
6c4009 |
killed. This is a BSD extension, and exists only in BSD systems and
|
|
Packit |
6c4009 |
@gnulinuxhurdsystems{}.
|
|
Packit |
6c4009 |
@end deftypevr
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@deftypevr Macro tcflag_t ECHONL
|
|
Packit |
6c4009 |
@standards{POSIX.1, termios.h}
|
|
Packit |
6c4009 |
If this bit is set and the @code{ICANON} bit is also set, then the
|
|
Packit |
6c4009 |
newline (@code{'\n'}) character is echoed even if the @code{ECHO} bit
|
|
Packit |
6c4009 |
is not set.
|
|
Packit |
6c4009 |
@end deftypevr
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@deftypevr Macro tcflag_t ECHOCTL
|
|
Packit |
6c4009 |
@standards{BSD, termios.h}
|
|
Packit |
6c4009 |
If this bit is set and the @code{ECHO} bit is also set, echo control
|
|
Packit |
6c4009 |
characters with @samp{^} followed by the corresponding text character.
|
|
Packit |
6c4009 |
Thus, control-A echoes as @samp{^A}. This is usually the preferred mode
|
|
Packit |
6c4009 |
for interactive input, because echoing a control character back to the
|
|
Packit |
6c4009 |
terminal could have some undesired effect on the terminal.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
This is a BSD extension, and exists only in BSD systems and
|
|
Packit |
6c4009 |
@gnulinuxhurdsystems{}.
|
|
Packit |
6c4009 |
@end deftypevr
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@deftypevr Macro tcflag_t ISIG
|
|
Packit |
6c4009 |
@standards{POSIX.1, termios.h}
|
|
Packit |
6c4009 |
This bit controls whether the INTR, QUIT, and SUSP characters are
|
|
Packit |
6c4009 |
recognized. The functions associated with these characters are performed
|
|
Packit |
6c4009 |
if and only if this bit is set. Being in canonical or noncanonical
|
|
Packit |
6c4009 |
input mode has no effect on the interpretation of these characters.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
You should use caution when disabling recognition of these characters.
|
|
Packit |
6c4009 |
Programs that cannot be interrupted interactively are very
|
|
Packit |
6c4009 |
user-unfriendly. If you clear this bit, your program should provide
|
|
Packit |
6c4009 |
some alternate interface that allows the user to interactively send the
|
|
Packit |
6c4009 |
signals associated with these characters, or to escape from the program.
|
|
Packit |
6c4009 |
@cindex interactive signals, from terminal
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@xref{Signal Characters}.
|
|
Packit |
6c4009 |
@end deftypevr
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@deftypevr Macro tcflag_t IEXTEN
|
|
Packit |
6c4009 |
@standards{POSIX.1, termios.h}
|
|
Packit |
6c4009 |
POSIX.1 gives @code{IEXTEN} implementation-defined meaning,
|
|
Packit |
6c4009 |
so you cannot rely on this interpretation on all systems.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
On BSD systems and @gnulinuxhurdsystems{}, it enables the LNEXT and
|
|
Packit |
6c4009 |
DISCARD characters.
|
|
Packit |
6c4009 |
@xref{Other Special}.
|
|
Packit |
6c4009 |
@end deftypevr
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@deftypevr Macro tcflag_t NOFLSH
|
|
Packit |
6c4009 |
@standards{POSIX.1, termios.h}
|
|
Packit |
6c4009 |
Normally, the INTR, QUIT, and SUSP characters cause input and output
|
|
Packit |
6c4009 |
queues for the terminal to be cleared. If this bit is set, the queues
|
|
Packit |
6c4009 |
are not cleared.
|
|
Packit |
6c4009 |
@end deftypevr
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@deftypevr Macro tcflag_t TOSTOP
|
|
Packit |
6c4009 |
@standards{POSIX.1, termios.h}
|
|
Packit |
6c4009 |
If this bit is set and the system supports job control, then
|
|
Packit |
6c4009 |
@code{SIGTTOU} signals are generated by background processes that
|
|
Packit |
6c4009 |
attempt to write to the terminal. @xref{Access to the Terminal}.
|
|
Packit |
6c4009 |
@end deftypevr
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
The following bits are BSD extensions; they exist only on BSD systems
|
|
Packit |
6c4009 |
and @gnuhurdsystems{}.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@deftypevr Macro tcflag_t ALTWERASE
|
|
Packit |
6c4009 |
@standards{BSD, termios.h}
|
|
Packit |
6c4009 |
This bit determines how far the WERASE character should erase. The
|
|
Packit |
6c4009 |
WERASE character erases back to the beginning of a word; the question
|
|
Packit |
6c4009 |
is, where do words begin?
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
If this bit is clear, then the beginning of a word is a nonwhitespace
|
|
Packit |
6c4009 |
character following a whitespace character. If the bit is set, then the
|
|
Packit |
6c4009 |
beginning of a word is an alphanumeric character or underscore following
|
|
Packit |
6c4009 |
a character which is none of those.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@xref{Editing Characters}, for more information about the WERASE character.
|
|
Packit |
6c4009 |
@end deftypevr
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@deftypevr Macro tcflag_t FLUSHO
|
|
Packit |
6c4009 |
@standards{BSD, termios.h}
|
|
Packit |
6c4009 |
This is the bit that toggles when the user types the DISCARD character.
|
|
Packit |
6c4009 |
While this bit is set, all output is discarded. @xref{Other Special}.
|
|
Packit |
6c4009 |
@end deftypevr
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@deftypevr Macro tcflag_t NOKERNINFO
|
|
Packit |
6c4009 |
@standards{BSD, termios.h (optional)}
|
|
Packit |
6c4009 |
Setting this bit disables handling of the STATUS character.
|
|
Packit |
6c4009 |
@xref{Other Special}.
|
|
Packit |
6c4009 |
@end deftypevr
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@deftypevr Macro tcflag_t PENDIN
|
|
Packit |
6c4009 |
@standards{BSD, termios.h}
|
|
Packit |
6c4009 |
If this bit is set, it indicates that there is a line of input that
|
|
Packit |
6c4009 |
needs to be reprinted. Typing the REPRINT character sets this bit; the
|
|
Packit |
6c4009 |
bit remains set until reprinting is finished. @xref{Editing Characters}.
|
|
Packit |
6c4009 |
@end deftypevr
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@c EXTPROC is too obscure to document now. --roland
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@node Line Speed
|
|
Packit |
6c4009 |
@subsection Line Speed
|
|
Packit |
6c4009 |
@cindex line speed
|
|
Packit |
6c4009 |
@cindex baud rate
|
|
Packit |
6c4009 |
@cindex terminal line speed
|
|
Packit |
6c4009 |
@cindex terminal line speed
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
The terminal line speed tells the computer how fast to read and write
|
|
Packit |
6c4009 |
data on the terminal.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
If the terminal is connected to a real serial line, the terminal speed
|
|
Packit |
6c4009 |
you specify actually controls the line---if it doesn't match the
|
|
Packit |
6c4009 |
terminal's own idea of the speed, communication does not work. Real
|
|
Packit |
6c4009 |
serial ports accept only certain standard speeds. Also, particular
|
|
Packit |
6c4009 |
hardware may not support even all the standard speeds. Specifying a
|
|
Packit |
6c4009 |
speed of zero hangs up a dialup connection and turns off modem control
|
|
Packit |
6c4009 |
signals.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
If the terminal is not a real serial line (for example, if it is a
|
|
Packit |
6c4009 |
network connection), then the line speed won't really affect data
|
|
Packit |
6c4009 |
transmission speed, but some programs will use it to determine the
|
|
Packit |
6c4009 |
amount of padding needed. It's best to specify a line speed value that
|
|
Packit |
6c4009 |
matches the actual speed of the actual terminal, but you can safely
|
|
Packit |
6c4009 |
experiment with different values to vary the amount of padding.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
There are actually two line speeds for each terminal, one for input and
|
|
Packit |
6c4009 |
one for output. You can set them independently, but most often
|
|
Packit |
6c4009 |
terminals use the same speed for both directions.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
The speed values are stored in the @code{struct termios} structure, but
|
|
Packit |
6c4009 |
don't try to access them in the @code{struct termios} structure
|
|
Packit |
6c4009 |
directly. Instead, you should use the following functions to read and
|
|
Packit |
6c4009 |
store them:
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@deftypefun speed_t cfgetospeed (const struct termios *@var{termios-p})
|
|
Packit |
6c4009 |
@standards{POSIX.1, termios.h}
|
|
Packit |
6c4009 |
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
|
|
Packit |
6c4009 |
@c Direct access to a single termios field, except on Linux, where
|
|
Packit |
6c4009 |
@c multiple accesses may take place. No worries either way, callers
|
|
Packit |
6c4009 |
@c must ensure mutual exclusion on such non-opaque types.
|
|
Packit |
6c4009 |
This function returns the output line speed stored in the structure
|
|
Packit |
6c4009 |
@code{*@var{termios-p}}.
|
|
Packit |
6c4009 |
@end deftypefun
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@deftypefun speed_t cfgetispeed (const struct termios *@var{termios-p})
|
|
Packit |
6c4009 |
@standards{POSIX.1, termios.h}
|
|
Packit |
6c4009 |
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
|
|
Packit |
6c4009 |
This function returns the input line speed stored in the structure
|
|
Packit |
6c4009 |
@code{*@var{termios-p}}.
|
|
Packit |
6c4009 |
@end deftypefun
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@deftypefun int cfsetospeed (struct termios *@var{termios-p}, speed_t @var{speed})
|
|
Packit |
6c4009 |
@standards{POSIX.1, termios.h}
|
|
Packit |
6c4009 |
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
|
|
Packit |
6c4009 |
This function stores @var{speed} in @code{*@var{termios-p}} as the output
|
|
Packit |
6c4009 |
speed. The normal return value is @math{0}; a value of @math{-1}
|
|
Packit |
6c4009 |
indicates an error. If @var{speed} is not a speed, @code{cfsetospeed}
|
|
Packit |
6c4009 |
returns @math{-1}.
|
|
Packit |
6c4009 |
@end deftypefun
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@deftypefun int cfsetispeed (struct termios *@var{termios-p}, speed_t @var{speed})
|
|
Packit |
6c4009 |
@standards{POSIX.1, termios.h}
|
|
Packit |
6c4009 |
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
|
|
Packit |
6c4009 |
This function stores @var{speed} in @code{*@var{termios-p}} as the input
|
|
Packit |
6c4009 |
speed. The normal return value is @math{0}; a value of @math{-1}
|
|
Packit |
6c4009 |
indicates an error. If @var{speed} is not a speed, @code{cfsetospeed}
|
|
Packit |
6c4009 |
returns @math{-1}.
|
|
Packit |
6c4009 |
@end deftypefun
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@deftypefun int cfsetspeed (struct termios *@var{termios-p}, speed_t @var{speed})
|
|
Packit |
6c4009 |
@standards{BSD, termios.h}
|
|
Packit |
6c4009 |
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
|
|
Packit |
6c4009 |
@c There's no guarantee that the two calls are atomic, but since this is
|
|
Packit |
6c4009 |
@c not an opaque type, callers ought to ensure mutual exclusion to the
|
|
Packit |
6c4009 |
@c termios object.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@c cfsetspeed ok
|
|
Packit |
6c4009 |
@c cfsetispeed ok
|
|
Packit |
6c4009 |
@c cfsetospeed ok
|
|
Packit |
6c4009 |
This function stores @var{speed} in @code{*@var{termios-p}} as both the
|
|
Packit |
6c4009 |
input and output speeds. The normal return value is @math{0}; a value
|
|
Packit |
6c4009 |
of @math{-1} indicates an error. If @var{speed} is not a speed,
|
|
Packit |
6c4009 |
@code{cfsetspeed} returns @math{-1}. This function is an extension in
|
|
Packit |
6c4009 |
4.4 BSD.
|
|
Packit |
6c4009 |
@end deftypefun
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@deftp {Data Type} speed_t
|
|
Packit |
6c4009 |
@standards{POSIX.1, termios.h}
|
|
Packit |
6c4009 |
The @code{speed_t} type is an unsigned integer data type used to
|
|
Packit |
6c4009 |
represent line speeds.
|
|
Packit |
6c4009 |
@end deftp
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
The functions @code{cfsetospeed} and @code{cfsetispeed} report errors
|
|
Packit |
6c4009 |
only for speed values that the system simply cannot handle. If you
|
|
Packit |
6c4009 |
specify a speed value that is basically acceptable, then those functions
|
|
Packit |
6c4009 |
will succeed. But they do not check that a particular hardware device
|
|
Packit |
6c4009 |
can actually support the specified speeds---in fact, they don't know
|
|
Packit |
6c4009 |
which device you plan to set the speed for. If you use @code{tcsetattr}
|
|
Packit |
6c4009 |
to set the speed of a particular device to a value that it cannot
|
|
Packit |
6c4009 |
handle, @code{tcsetattr} returns @math{-1}.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@strong{Portability note:} In @theglibc{}, the functions above
|
|
Packit |
6c4009 |
accept speeds measured in bits per second as input, and return speed
|
|
Packit |
6c4009 |
values measured in bits per second. Other libraries require speeds to
|
|
Packit |
6c4009 |
be indicated by special codes. For POSIX.1 portability, you must use
|
|
Packit |
6c4009 |
one of the following symbols to represent the speed; their precise
|
|
Packit |
6c4009 |
numeric values are system-dependent, but each name has a fixed meaning:
|
|
Packit |
6c4009 |
@code{B110} stands for 110 bps, @code{B300} for 300 bps, and so on.
|
|
Packit |
6c4009 |
There is no portable way to represent any speed but these, but these are
|
|
Packit |
6c4009 |
the only speeds that typical serial lines can support.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@comment termios.h
|
|
Packit |
6c4009 |
@comment POSIX.1
|
|
Packit |
6c4009 |
@vindex B0
|
|
Packit |
6c4009 |
@comment termios.h
|
|
Packit |
6c4009 |
@comment POSIX.1
|
|
Packit |
6c4009 |
@vindex B50
|
|
Packit |
6c4009 |
@comment termios.h
|
|
Packit |
6c4009 |
@comment POSIX.1
|
|
Packit |
6c4009 |
@vindex B75
|
|
Packit |
6c4009 |
@comment termios.h
|
|
Packit |
6c4009 |
@comment POSIX.1
|
|
Packit |
6c4009 |
@vindex B110
|
|
Packit |
6c4009 |
@comment termios.h
|
|
Packit |
6c4009 |
@comment POSIX.1
|
|
Packit |
6c4009 |
@vindex B134
|
|
Packit |
6c4009 |
@comment termios.h
|
|
Packit |
6c4009 |
@comment POSIX.1
|
|
Packit |
6c4009 |
@vindex B150
|
|
Packit |
6c4009 |
@comment termios.h
|
|
Packit |
6c4009 |
@comment POSIX.1
|
|
Packit |
6c4009 |
@vindex B200
|
|
Packit |
6c4009 |
@comment termios.h
|
|
Packit |
6c4009 |
@comment POSIX.1
|
|
Packit |
6c4009 |
@vindex B300
|
|
Packit |
6c4009 |
@comment termios.h
|
|
Packit |
6c4009 |
@comment POSIX.1
|
|
Packit |
6c4009 |
@vindex B600
|
|
Packit |
6c4009 |
@comment termios.h
|
|
Packit |
6c4009 |
@comment POSIX.1
|
|
Packit |
6c4009 |
@vindex B1200
|
|
Packit |
6c4009 |
@comment termios.h
|
|
Packit |
6c4009 |
@comment POSIX.1
|
|
Packit |
6c4009 |
@vindex B1800
|
|
Packit |
6c4009 |
@comment termios.h
|
|
Packit |
6c4009 |
@comment POSIX.1
|
|
Packit |
6c4009 |
@vindex B2400
|
|
Packit |
6c4009 |
@comment termios.h
|
|
Packit |
6c4009 |
@comment POSIX.1
|
|
Packit |
6c4009 |
@vindex B4800
|
|
Packit |
6c4009 |
@comment termios.h
|
|
Packit |
6c4009 |
@comment POSIX.1
|
|
Packit |
6c4009 |
@vindex B9600
|
|
Packit |
6c4009 |
@comment termios.h
|
|
Packit |
6c4009 |
@comment POSIX.1
|
|
Packit |
6c4009 |
@vindex B19200
|
|
Packit |
6c4009 |
@comment termios.h
|
|
Packit |
6c4009 |
@comment POSIX.1
|
|
Packit |
6c4009 |
@vindex B38400
|
|
Packit |
6c4009 |
@comment termios.h
|
|
Packit |
6c4009 |
@comment GNU
|
|
Packit |
6c4009 |
@vindex B57600
|
|
Packit |
6c4009 |
@comment termios.h
|
|
Packit |
6c4009 |
@comment GNU
|
|
Packit |
6c4009 |
@vindex B115200
|
|
Packit |
6c4009 |
@comment termios.h
|
|
Packit |
6c4009 |
@comment GNU
|
|
Packit |
6c4009 |
@vindex B230400
|
|
Packit |
6c4009 |
@comment termios.h
|
|
Packit |
6c4009 |
@comment GNU
|
|
Packit |
6c4009 |
@vindex B460800
|
|
Packit |
6c4009 |
@smallexample
|
|
Packit |
6c4009 |
B0 B50 B75 B110 B134 B150 B200
|
|
Packit |
6c4009 |
B300 B600 B1200 B1800 B2400 B4800
|
|
Packit |
6c4009 |
B9600 B19200 B38400 B57600 B115200
|
|
Packit |
6c4009 |
B230400 B460800
|
|
Packit |
6c4009 |
@end smallexample
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@vindex EXTA
|
|
Packit |
6c4009 |
@vindex EXTB
|
|
Packit |
6c4009 |
BSD defines two additional speed symbols as aliases: @code{EXTA} is an
|
|
Packit |
6c4009 |
alias for @code{B19200} and @code{EXTB} is an alias for @code{B38400}.
|
|
Packit |
6c4009 |
These aliases are obsolete.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@node Special Characters
|
|
Packit |
6c4009 |
@subsection Special Characters
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
In canonical input, the terminal driver recognizes a number of special
|
|
Packit |
6c4009 |
characters which perform various control functions. These include the
|
|
Packit |
6c4009 |
ERASE character (usually @key{DEL}) for editing input, and other editing
|
|
Packit |
6c4009 |
characters. The INTR character (normally @kbd{C-c}) for sending a
|
|
Packit |
6c4009 |
@code{SIGINT} signal, and other signal-raising characters, may be
|
|
Packit |
6c4009 |
available in either canonical or noncanonical input mode. All these
|
|
Packit |
6c4009 |
characters are described in this section.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
The particular characters used are specified in the @code{c_cc} member
|
|
Packit |
6c4009 |
of the @code{struct termios} structure. This member is an array; each
|
|
Packit |
6c4009 |
element specifies the character for a particular role. Each element has
|
|
Packit |
6c4009 |
a symbolic constant that stands for the index of that element---for
|
|
Packit |
6c4009 |
example, @code{VINTR} is the index of the element that specifies the INTR
|
|
Packit |
6c4009 |
character, so storing @code{'='} in @code{@var{termios}.c_cc[VINTR]}
|
|
Packit |
6c4009 |
specifies @samp{=} as the INTR character.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@vindex _POSIX_VDISABLE
|
|
Packit |
6c4009 |
On some systems, you can disable a particular special character function
|
|
Packit |
6c4009 |
by specifying the value @code{_POSIX_VDISABLE} for that role. This
|
|
Packit |
6c4009 |
value is unequal to any possible character code. @xref{Options for
|
|
Packit |
6c4009 |
Files}, for more information about how to tell whether the operating
|
|
Packit |
6c4009 |
system you are using supports @code{_POSIX_VDISABLE}.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@menu
|
|
Packit |
6c4009 |
* Editing Characters:: Special characters that terminate lines and
|
|
Packit |
6c4009 |
delete text, and other editing functions.
|
|
Packit |
6c4009 |
* Signal Characters:: Special characters that send or raise signals
|
|
Packit |
6c4009 |
to or for certain classes of processes.
|
|
Packit |
6c4009 |
* Start/Stop Characters:: Special characters that suspend or resume
|
|
Packit |
6c4009 |
suspended output.
|
|
Packit |
6c4009 |
* Other Special:: Other special characters for BSD systems:
|
|
Packit |
6c4009 |
they can discard output, and print status.
|
|
Packit |
6c4009 |
@end menu
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@node Editing Characters
|
|
Packit |
6c4009 |
@subsubsection Characters for Input Editing
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
These special characters are active only in canonical input mode.
|
|
Packit |
6c4009 |
@xref{Canonical or Not}.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@deftypevr Macro int VEOF
|
|
Packit |
6c4009 |
@standards{POSIX.1, termios.h}
|
|
Packit |
6c4009 |
@cindex EOF character
|
|
Packit |
6c4009 |
This is the subscript for the EOF character in the special control
|
|
Packit |
6c4009 |
character array. @code{@var{termios}.c_cc[VEOF]} holds the character
|
|
Packit |
6c4009 |
itself.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
The EOF character is recognized only in canonical input mode. It acts
|
|
Packit |
6c4009 |
as a line terminator in the same way as a newline character, but if the
|
|
Packit |
6c4009 |
EOF character is typed at the beginning of a line it causes @code{read}
|
|
Packit |
6c4009 |
to return a byte count of zero, indicating end-of-file. The EOF
|
|
Packit |
6c4009 |
character itself is discarded.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
Usually, the EOF character is @kbd{C-d}.
|
|
Packit |
6c4009 |
@end deftypevr
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@deftypevr Macro int VEOL
|
|
Packit |
6c4009 |
@standards{POSIX.1, termios.h}
|
|
Packit |
6c4009 |
@cindex EOL character
|
|
Packit |
6c4009 |
This is the subscript for the EOL character in the special control
|
|
Packit |
6c4009 |
character array. @code{@var{termios}.c_cc[VEOL]} holds the character
|
|
Packit |
6c4009 |
itself.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
The EOL character is recognized only in canonical input mode. It acts
|
|
Packit |
6c4009 |
as a line terminator, just like a newline character. The EOL character
|
|
Packit |
6c4009 |
is not discarded; it is read as the last character in the input line.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@c !!! example: this is set to ESC by 4.3 csh with "set filec" so it can
|
|
Packit |
6c4009 |
@c complete partial lines without using cbreak or raw mode.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
You don't need to use the EOL character to make @key{RET} end a line.
|
|
Packit |
6c4009 |
Just set the ICRNL flag. In fact, this is the default state of
|
|
Packit |
6c4009 |
affairs.
|
|
Packit |
6c4009 |
@end deftypevr
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@deftypevr Macro int VEOL2
|
|
Packit |
6c4009 |
@standards{BSD, termios.h}
|
|
Packit |
6c4009 |
@cindex EOL2 character
|
|
Packit |
6c4009 |
This is the subscript for the EOL2 character in the special control
|
|
Packit |
6c4009 |
character array. @code{@var{termios}.c_cc[VEOL2]} holds the character
|
|
Packit |
6c4009 |
itself.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
The EOL2 character works just like the EOL character (see above), but it
|
|
Packit |
6c4009 |
can be a different character. Thus, you can specify two characters to
|
|
Packit |
6c4009 |
terminate an input line, by setting EOL to one of them and EOL2 to the
|
|
Packit |
6c4009 |
other.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
The EOL2 character is a BSD extension; it exists only on BSD systems
|
|
Packit |
6c4009 |
and @gnulinuxhurdsystems{}.
|
|
Packit |
6c4009 |
@end deftypevr
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@deftypevr Macro int VERASE
|
|
Packit |
6c4009 |
@standards{POSIX.1, termios.h}
|
|
Packit |
6c4009 |
@cindex ERASE character
|
|
Packit |
6c4009 |
This is the subscript for the ERASE character in the special control
|
|
Packit |
6c4009 |
character array. @code{@var{termios}.c_cc[VERASE]} holds the
|
|
Packit |
6c4009 |
character itself.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
The ERASE character is recognized only in canonical input mode. When
|
|
Packit |
6c4009 |
the user types the erase character, the previous character typed is
|
|
Packit |
6c4009 |
discarded. (If the terminal generates multibyte character sequences,
|
|
Packit |
6c4009 |
this may cause more than one byte of input to be discarded.) This
|
|
Packit |
6c4009 |
cannot be used to erase past the beginning of the current line of text.
|
|
Packit |
6c4009 |
The ERASE character itself is discarded.
|
|
Packit |
6c4009 |
@c !!! mention ECHOE here
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
Usually, the ERASE character is @key{DEL}.
|
|
Packit |
6c4009 |
@end deftypevr
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@deftypevr Macro int VWERASE
|
|
Packit |
6c4009 |
@standards{BSD, termios.h}
|
|
Packit |
6c4009 |
@cindex WERASE character
|
|
Packit |
6c4009 |
This is the subscript for the WERASE character in the special control
|
|
Packit |
6c4009 |
character array. @code{@var{termios}.c_cc[VWERASE]} holds the character
|
|
Packit |
6c4009 |
itself.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
The WERASE character is recognized only in canonical mode. It erases an
|
|
Packit |
6c4009 |
entire word of prior input, and any whitespace after it; whitespace
|
|
Packit |
6c4009 |
characters before the word are not erased.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
The definition of a ``word'' depends on the setting of the
|
|
Packit |
6c4009 |
@code{ALTWERASE} mode; @pxref{Local Modes}.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
If the @code{ALTWERASE} mode is not set, a word is defined as a sequence
|
|
Packit |
6c4009 |
of any characters except space or tab.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
If the @code{ALTWERASE} mode is set, a word is defined as a sequence of
|
|
Packit |
6c4009 |
characters containing only letters, numbers, and underscores, optionally
|
|
Packit |
6c4009 |
followed by one character that is not a letter, number, or underscore.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
The WERASE character is usually @kbd{C-w}.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
This is a BSD extension.
|
|
Packit |
6c4009 |
@end deftypevr
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@deftypevr Macro int VKILL
|
|
Packit |
6c4009 |
@standards{POSIX.1, termios.h}
|
|
Packit |
6c4009 |
@cindex KILL character
|
|
Packit |
6c4009 |
This is the subscript for the KILL character in the special control
|
|
Packit |
6c4009 |
character array. @code{@var{termios}.c_cc[VKILL]} holds the character
|
|
Packit |
6c4009 |
itself.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
The KILL character is recognized only in canonical input mode. When the
|
|
Packit |
6c4009 |
user types the kill character, the entire contents of the current line
|
|
Packit |
6c4009 |
of input are discarded. The kill character itself is discarded too.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
The KILL character is usually @kbd{C-u}.
|
|
Packit |
6c4009 |
@end deftypevr
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@deftypevr Macro int VREPRINT
|
|
Packit |
6c4009 |
@standards{BSD, termios.h}
|
|
Packit |
6c4009 |
@cindex REPRINT character
|
|
Packit |
6c4009 |
This is the subscript for the REPRINT character in the special control
|
|
Packit |
6c4009 |
character array. @code{@var{termios}.c_cc[VREPRINT]} holds the character
|
|
Packit |
6c4009 |
itself.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
The REPRINT character is recognized only in canonical mode. It reprints
|
|
Packit |
6c4009 |
the current input line. If some asynchronous output has come while you
|
|
Packit |
6c4009 |
are typing, this lets you see the line you are typing clearly again.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
The REPRINT character is usually @kbd{C-r}.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
This is a BSD extension.
|
|
Packit |
6c4009 |
@end deftypevr
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@node Signal Characters
|
|
Packit |
6c4009 |
@subsubsection Characters that Cause Signals
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
These special characters may be active in either canonical or noncanonical
|
|
Packit |
6c4009 |
input mode, but only when the @code{ISIG} flag is set (@pxref{Local
|
|
Packit |
6c4009 |
Modes}).
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@deftypevr Macro int VINTR
|
|
Packit |
6c4009 |
@standards{POSIX.1, termios.h}
|
|
Packit |
6c4009 |
@cindex INTR character
|
|
Packit |
6c4009 |
@cindex interrupt character
|
|
Packit |
6c4009 |
This is the subscript for the INTR character in the special control
|
|
Packit |
6c4009 |
character array. @code{@var{termios}.c_cc[VINTR]} holds the character
|
|
Packit |
6c4009 |
itself.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
The INTR (interrupt) character raises a @code{SIGINT} signal for all
|
|
Packit |
6c4009 |
processes in the foreground job associated with the terminal. The INTR
|
|
Packit |
6c4009 |
character itself is then discarded. @xref{Signal Handling}, for more
|
|
Packit |
6c4009 |
information about signals.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
Typically, the INTR character is @kbd{C-c}.
|
|
Packit |
6c4009 |
@end deftypevr
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@deftypevr Macro int VQUIT
|
|
Packit |
6c4009 |
@standards{POSIX.1, termios.h}
|
|
Packit |
6c4009 |
@cindex QUIT character
|
|
Packit |
6c4009 |
This is the subscript for the QUIT character in the special control
|
|
Packit |
6c4009 |
character array. @code{@var{termios}.c_cc[VQUIT]} holds the character
|
|
Packit |
6c4009 |
itself.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
The QUIT character raises a @code{SIGQUIT} signal for all processes in
|
|
Packit |
6c4009 |
the foreground job associated with the terminal. The QUIT character
|
|
Packit |
6c4009 |
itself is then discarded. @xref{Signal Handling}, for more information
|
|
Packit |
6c4009 |
about signals.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
Typically, the QUIT character is @kbd{C-\}.
|
|
Packit |
6c4009 |
@end deftypevr
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@deftypevr Macro int VSUSP
|
|
Packit |
6c4009 |
@standards{POSIX.1, termios.h}
|
|
Packit |
6c4009 |
@cindex SUSP character
|
|
Packit |
6c4009 |
@cindex suspend character
|
|
Packit |
6c4009 |
This is the subscript for the SUSP character in the special control
|
|
Packit |
6c4009 |
character array. @code{@var{termios}.c_cc[VSUSP]} holds the character
|
|
Packit |
6c4009 |
itself.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
The SUSP (suspend) character is recognized only if the implementation
|
|
Packit |
6c4009 |
supports job control (@pxref{Job Control}). It causes a @code{SIGTSTP}
|
|
Packit |
6c4009 |
signal to be sent to all processes in the foreground job associated with
|
|
Packit |
6c4009 |
the terminal. The SUSP character itself is then discarded.
|
|
Packit |
6c4009 |
@xref{Signal Handling}, for more information about signals.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
Typically, the SUSP character is @kbd{C-z}.
|
|
Packit |
6c4009 |
@end deftypevr
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
Few applications disable the normal interpretation of the SUSP
|
|
Packit |
6c4009 |
character. If your program does this, it should provide some other
|
|
Packit |
6c4009 |
mechanism for the user to stop the job. When the user invokes this
|
|
Packit |
6c4009 |
mechanism, the program should send a @code{SIGTSTP} signal to the
|
|
Packit |
6c4009 |
process group of the process, not just to the process itself.
|
|
Packit |
6c4009 |
@xref{Signaling Another Process}.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@deftypevr Macro int VDSUSP
|
|
Packit |
6c4009 |
@standards{BSD, termios.h}
|
|
Packit |
6c4009 |
@cindex DSUSP character
|
|
Packit |
6c4009 |
@cindex delayed suspend character
|
|
Packit |
6c4009 |
This is the subscript for the DSUSP character in the special control
|
|
Packit |
6c4009 |
character array. @code{@var{termios}.c_cc[VDSUSP]} holds the character
|
|
Packit |
6c4009 |
itself.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
The DSUSP (suspend) character is recognized only if the implementation
|
|
Packit |
6c4009 |
supports job control (@pxref{Job Control}). It sends a @code{SIGTSTP}
|
|
Packit |
6c4009 |
signal, like the SUSP character, but not right away---only when the
|
|
Packit |
6c4009 |
program tries to read it as input. Not all systems with job control
|
|
Packit |
6c4009 |
support DSUSP; only BSD-compatible systems do (including @gnuhurdsystems{}).
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@xref{Signal Handling}, for more information about signals.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
Typically, the DSUSP character is @kbd{C-y}.
|
|
Packit |
6c4009 |
@end deftypevr
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@node Start/Stop Characters
|
|
Packit |
6c4009 |
@subsubsection Special Characters for Flow Control
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
These special characters may be active in either canonical or noncanonical
|
|
Packit |
6c4009 |
input mode, but their use is controlled by the flags @code{IXON} and
|
|
Packit |
6c4009 |
@code{IXOFF} (@pxref{Input Modes}).
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@deftypevr Macro int VSTART
|
|
Packit |
6c4009 |
@standards{POSIX.1, termios.h}
|
|
Packit |
6c4009 |
@cindex START character
|
|
Packit |
6c4009 |
This is the subscript for the START character in the special control
|
|
Packit |
6c4009 |
character array. @code{@var{termios}.c_cc[VSTART]} holds the
|
|
Packit |
6c4009 |
character itself.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
The START character is used to support the @code{IXON} and @code{IXOFF}
|
|
Packit |
6c4009 |
input modes. If @code{IXON} is set, receiving a START character resumes
|
|
Packit |
6c4009 |
suspended output; the START character itself is discarded. If
|
|
Packit |
6c4009 |
@code{IXANY} is set, receiving any character at all resumes suspended
|
|
Packit |
6c4009 |
output; the resuming character is not discarded unless it is the START
|
|
Packit |
6c4009 |
character. If @code{IXOFF} is set, the system may also transmit START
|
|
Packit |
6c4009 |
characters to the terminal.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
The usual value for the START character is @kbd{C-q}. You may not be
|
|
Packit |
6c4009 |
able to change this value---the hardware may insist on using @kbd{C-q}
|
|
Packit |
6c4009 |
regardless of what you specify.
|
|
Packit |
6c4009 |
@end deftypevr
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@deftypevr Macro int VSTOP
|
|
Packit |
6c4009 |
@standards{POSIX.1, termios.h}
|
|
Packit |
6c4009 |
@cindex STOP character
|
|
Packit |
6c4009 |
This is the subscript for the STOP character in the special control
|
|
Packit |
6c4009 |
character array. @code{@var{termios}.c_cc[VSTOP]} holds the character
|
|
Packit |
6c4009 |
itself.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
The STOP character is used to support the @code{IXON} and @code{IXOFF}
|
|
Packit |
6c4009 |
input modes. If @code{IXON} is set, receiving a STOP character causes
|
|
Packit |
6c4009 |
output to be suspended; the STOP character itself is discarded. If
|
|
Packit |
6c4009 |
@code{IXOFF} is set, the system may also transmit STOP characters to the
|
|
Packit |
6c4009 |
terminal, to prevent the input queue from overflowing.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
The usual value for the STOP character is @kbd{C-s}. You may not be
|
|
Packit |
6c4009 |
able to change this value---the hardware may insist on using @kbd{C-s}
|
|
Packit |
6c4009 |
regardless of what you specify.
|
|
Packit |
6c4009 |
@end deftypevr
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@node Other Special
|
|
Packit |
6c4009 |
@subsubsection Other Special Characters
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@deftypevr Macro int VLNEXT
|
|
Packit |
6c4009 |
@standards{BSD, termios.h}
|
|
Packit |
6c4009 |
@cindex LNEXT character
|
|
Packit |
6c4009 |
This is the subscript for the LNEXT character in the special control
|
|
Packit |
6c4009 |
character array. @code{@var{termios}.c_cc[VLNEXT]} holds the character
|
|
Packit |
6c4009 |
itself.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
The LNEXT character is recognized only when @code{IEXTEN} is set, but in
|
|
Packit |
6c4009 |
both canonical and noncanonical mode. It disables any special
|
|
Packit |
6c4009 |
significance of the next character the user types. Even if the
|
|
Packit |
6c4009 |
character would normally perform some editing function or generate a
|
|
Packit |
6c4009 |
signal, it is read as a plain character. This is the analogue of the
|
|
Packit |
6c4009 |
@kbd{C-q} command in Emacs. ``LNEXT'' stands for ``literal next.''
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
The LNEXT character is usually @kbd{C-v}.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
This character is available on BSD systems and @gnulinuxhurdsystems{}.
|
|
Packit |
6c4009 |
@end deftypevr
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@deftypevr Macro int VDISCARD
|
|
Packit |
6c4009 |
@standards{BSD, termios.h}
|
|
Packit |
6c4009 |
@cindex DISCARD character
|
|
Packit |
6c4009 |
This is the subscript for the DISCARD character in the special control
|
|
Packit |
6c4009 |
character array. @code{@var{termios}.c_cc[VDISCARD]} holds the character
|
|
Packit |
6c4009 |
itself.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
The DISCARD character is recognized only when @code{IEXTEN} is set, but
|
|
Packit |
6c4009 |
in both canonical and noncanonical mode. Its effect is to toggle the
|
|
Packit |
6c4009 |
discard-output flag. When this flag is set, all program output is
|
|
Packit |
6c4009 |
discarded. Setting the flag also discards all output currently in the
|
|
Packit |
6c4009 |
output buffer. Typing any other character resets the flag.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
This character is available on BSD systems and @gnulinuxhurdsystems{}.
|
|
Packit |
6c4009 |
@end deftypevr
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@deftypevr Macro int VSTATUS
|
|
Packit |
6c4009 |
@standards{BSD, termios.h}
|
|
Packit |
6c4009 |
@cindex STATUS character
|
|
Packit |
6c4009 |
This is the subscript for the STATUS character in the special control
|
|
Packit |
6c4009 |
character array. @code{@var{termios}.c_cc[VSTATUS]} holds the character
|
|
Packit |
6c4009 |
itself.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
The STATUS character's effect is to print out a status message about how
|
|
Packit |
6c4009 |
the current process is running.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
The STATUS character is recognized only in canonical mode, and only if
|
|
Packit |
6c4009 |
@code{NOKERNINFO} is not set.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
This character is available only on BSD systems and @gnuhurdsystems{}.
|
|
Packit |
6c4009 |
@end deftypevr
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@node Noncanonical Input
|
|
Packit |
6c4009 |
@subsection Noncanonical Input
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
In noncanonical input mode, the special editing characters such as
|
|
Packit |
6c4009 |
ERASE and KILL are ignored. The system facilities for the user to edit
|
|
Packit |
6c4009 |
input are disabled in noncanonical mode, so that all input characters
|
|
Packit |
6c4009 |
(unless they are special for signal or flow-control purposes) are passed
|
|
Packit |
6c4009 |
to the application program exactly as typed. It is up to the
|
|
Packit |
6c4009 |
application program to give the user ways to edit the input, if
|
|
Packit |
6c4009 |
appropriate.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
Noncanonical mode offers special parameters called MIN and TIME for
|
|
Packit |
6c4009 |
controlling whether and how long to wait for input to be available. You
|
|
Packit |
6c4009 |
can even use them to avoid ever waiting---to return immediately with
|
|
Packit |
6c4009 |
whatever input is available, or with no input.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
The MIN and TIME are stored in elements of the @code{c_cc} array, which
|
|
Packit |
6c4009 |
is a member of the @w{@code{struct termios}} structure. Each element of
|
|
Packit |
6c4009 |
this array has a particular role, and each element has a symbolic
|
|
Packit |
6c4009 |
constant that stands for the index of that element. @code{VMIN} and
|
|
Packit |
6c4009 |
@code{VTIME} are the names for the indices in the array of the MIN and
|
|
Packit |
6c4009 |
TIME slots.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@deftypevr Macro int VMIN
|
|
Packit |
6c4009 |
@standards{POSIX.1, termios.h}
|
|
Packit |
6c4009 |
@cindex MIN termios slot
|
|
Packit |
6c4009 |
This is the subscript for the MIN slot in the @code{c_cc} array. Thus,
|
|
Packit |
6c4009 |
@code{@var{termios}.c_cc[VMIN]} is the value itself.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
The MIN slot is only meaningful in noncanonical input mode; it
|
|
Packit |
6c4009 |
specifies the minimum number of bytes that must be available in the
|
|
Packit |
6c4009 |
input queue in order for @code{read} to return.
|
|
Packit |
6c4009 |
@end deftypevr
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@deftypevr Macro int VTIME
|
|
Packit |
6c4009 |
@standards{POSIX.1, termios.h}
|
|
Packit |
6c4009 |
@cindex TIME termios slot
|
|
Packit |
6c4009 |
This is the subscript for the TIME slot in the @code{c_cc} array. Thus,
|
|
Packit |
6c4009 |
@code{@var{termios}.c_cc[VTIME]} is the value itself.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
The TIME slot is only meaningful in noncanonical input mode; it
|
|
Packit |
6c4009 |
specifies how long to wait for input before returning, in units of 0.1
|
|
Packit |
6c4009 |
seconds.
|
|
Packit |
6c4009 |
@end deftypevr
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
The MIN and TIME values interact to determine the criterion for when
|
|
Packit |
6c4009 |
@code{read} should return; their precise meanings depend on which of
|
|
Packit |
6c4009 |
them are nonzero. There are four possible cases:
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@itemize @bullet
|
|
Packit |
6c4009 |
@item
|
|
Packit |
6c4009 |
Both TIME and MIN are nonzero.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
In this case, TIME specifies how long to wait after each input character
|
|
Packit |
6c4009 |
to see if more input arrives. After the first character received,
|
|
Packit |
6c4009 |
@code{read} keeps waiting until either MIN bytes have arrived in all, or
|
|
Packit |
6c4009 |
TIME elapses with no further input.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@code{read} always blocks until the first character arrives, even if
|
|
Packit |
6c4009 |
TIME elapses first. @code{read} can return more than MIN characters if
|
|
Packit |
6c4009 |
more than MIN happen to be in the queue.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@item
|
|
Packit |
6c4009 |
Both MIN and TIME are zero.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
In this case, @code{read} always returns immediately with as many
|
|
Packit |
6c4009 |
characters as are available in the queue, up to the number requested.
|
|
Packit |
6c4009 |
If no input is immediately available, @code{read} returns a value of
|
|
Packit |
6c4009 |
zero.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@item
|
|
Packit |
6c4009 |
MIN is zero but TIME has a nonzero value.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
In this case, @code{read} waits for time TIME for input to become
|
|
Packit |
6c4009 |
available; the availability of a single byte is enough to satisfy the
|
|
Packit |
6c4009 |
read request and cause @code{read} to return. When it returns, it
|
|
Packit |
6c4009 |
returns as many characters as are available, up to the number requested.
|
|
Packit |
6c4009 |
If no input is available before the timer expires, @code{read} returns a
|
|
Packit |
6c4009 |
value of zero.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@item
|
|
Packit |
6c4009 |
TIME is zero but MIN has a nonzero value.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
In this case, @code{read} waits until at least MIN bytes are available
|
|
Packit |
6c4009 |
in the queue. At that time, @code{read} returns as many characters as
|
|
Packit |
6c4009 |
are available, up to the number requested. @code{read} can return more
|
|
Packit |
6c4009 |
than MIN characters if more than MIN happen to be in the queue.
|
|
Packit |
6c4009 |
@end itemize
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
What happens if MIN is 50 and you ask to read just 10 bytes?
|
|
Packit |
6c4009 |
Normally, @code{read} waits until there are 50 bytes in the buffer (or,
|
|
Packit |
6c4009 |
more generally, the wait condition described above is satisfied), and
|
|
Packit |
6c4009 |
then reads 10 of them, leaving the other 40 buffered in the operating
|
|
Packit |
6c4009 |
system for a subsequent call to @code{read}.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@strong{Portability note:} On some systems, the MIN and TIME slots are
|
|
Packit |
6c4009 |
actually the same as the EOF and EOL slots. This causes no serious
|
|
Packit |
6c4009 |
problem because the MIN and TIME slots are used only in noncanonical
|
|
Packit |
6c4009 |
input and the EOF and EOL slots are used only in canonical input, but it
|
|
Packit |
6c4009 |
isn't very clean. @Theglibc{} allocates separate slots for these
|
|
Packit |
6c4009 |
uses.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@deftypefun void cfmakeraw (struct termios *@var{termios-p})
|
|
Packit |
6c4009 |
@standards{BSD, termios.h}
|
|
Packit |
6c4009 |
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
|
|
Packit |
6c4009 |
@c There's no guarantee the changes are atomic, but since this is not an
|
|
Packit |
6c4009 |
@c opaque type, callers ought to ensure mutual exclusion to the termios
|
|
Packit |
6c4009 |
@c object.
|
|
Packit |
6c4009 |
This function provides an easy way to set up @code{*@var{termios-p}} for
|
|
Packit |
6c4009 |
what has traditionally been called ``raw mode'' in BSD. This uses
|
|
Packit |
6c4009 |
noncanonical input, and turns off most processing to give an unmodified
|
|
Packit |
6c4009 |
channel to the terminal.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
It does exactly this:
|
|
Packit |
6c4009 |
@smallexample
|
|
Packit |
6c4009 |
@var{termios-p}->c_iflag &= ~(IGNBRK|BRKINT|PARMRK|ISTRIP
|
|
Packit |
6c4009 |
|INLCR|IGNCR|ICRNL|IXON);
|
|
Packit |
6c4009 |
@var{termios-p}->c_oflag &= ~OPOST;
|
|
Packit |
6c4009 |
@var{termios-p}->c_lflag &= ~(ECHO|ECHONL|ICANON|ISIG|IEXTEN);
|
|
Packit |
6c4009 |
@var{termios-p}->c_cflag &= ~(CSIZE|PARENB);
|
|
Packit |
6c4009 |
@var{termios-p}->c_cflag |= CS8;
|
|
Packit |
6c4009 |
@end smallexample
|
|
Packit |
6c4009 |
@end deftypefun
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@node BSD Terminal Modes
|
|
Packit |
6c4009 |
@section BSD Terminal Modes
|
|
Packit |
6c4009 |
@cindex terminal modes, BSD
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
The usual way to get and set terminal modes is with the functions described
|
|
Packit |
6c4009 |
in @ref{Terminal Modes}. However, on some systems you can use the
|
|
Packit |
6c4009 |
BSD-derived functions in this section to do some of the same things. On
|
|
Packit |
6c4009 |
many systems, these functions do not exist. Even with @theglibc{},
|
|
Packit |
6c4009 |
the functions simply fail with @code{errno} = @code{ENOSYS} with many
|
|
Packit |
6c4009 |
kernels, including Linux.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
The symbols used in this section are declared in @file{sgtty.h}.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@deftp {Data Type} {struct sgttyb}
|
|
Packit |
6c4009 |
@standards{BSD, termios.h}
|
|
Packit |
6c4009 |
This structure is an input or output parameter list for @code{gtty} and
|
|
Packit |
6c4009 |
@code{stty}.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@table @code
|
|
Packit |
6c4009 |
@item char sg_ispeed
|
|
Packit |
6c4009 |
Line speed for input
|
|
Packit |
6c4009 |
@item char sg_ospeed
|
|
Packit |
6c4009 |
Line speed for output
|
|
Packit |
6c4009 |
@item char sg_erase
|
|
Packit |
6c4009 |
Erase character
|
|
Packit |
6c4009 |
@item char sg_kill
|
|
Packit |
6c4009 |
Kill character
|
|
Packit |
6c4009 |
@item int sg_flags
|
|
Packit |
6c4009 |
Various flags
|
|
Packit |
6c4009 |
@end table
|
|
Packit |
6c4009 |
@end deftp
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@deftypefun int gtty (int @var{filedes}, struct sgttyb *@var{attributes})
|
|
Packit |
6c4009 |
@standards{BSD, sgtty.h}
|
|
Packit |
6c4009 |
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
|
|
Packit |
6c4009 |
@c Direct ioctl, BSD only.
|
|
Packit |
6c4009 |
This function gets the attributes of a terminal.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@code{gtty} sets *@var{attributes} to describe the terminal attributes
|
|
Packit |
6c4009 |
of the terminal which is open with file descriptor @var{filedes}.
|
|
Packit |
6c4009 |
@end deftypefun
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@deftypefun int stty (int @var{filedes}, const struct sgttyb *@var{attributes})
|
|
Packit |
6c4009 |
@standards{BSD, sgtty.h}
|
|
Packit |
6c4009 |
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
|
|
Packit |
6c4009 |
@c Direct ioctl, BSD only.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
This function sets the attributes of a terminal.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@code{stty} sets the terminal attributes of the terminal which is open with
|
|
Packit |
6c4009 |
file descriptor @var{filedes} to those described by *@var{attributes}.
|
|
Packit |
6c4009 |
@end deftypefun
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@node Line Control
|
|
Packit |
6c4009 |
@section Line Control Functions
|
|
Packit |
6c4009 |
@cindex terminal line control functions
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
These functions perform miscellaneous control actions on terminal
|
|
Packit |
6c4009 |
devices. As regards terminal access, they are treated like doing
|
|
Packit |
6c4009 |
output: if any of these functions is used by a background process on its
|
|
Packit |
6c4009 |
controlling terminal, normally all processes in the process group are
|
|
Packit |
6c4009 |
sent a @code{SIGTTOU} signal. The exception is if the calling process
|
|
Packit |
6c4009 |
itself is ignoring or blocking @code{SIGTTOU} signals, in which case the
|
|
Packit |
6c4009 |
operation is performed and no signal is sent. @xref{Job Control}.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@cindex break condition, generating
|
|
Packit |
6c4009 |
@deftypefun int tcsendbreak (int @var{filedes}, int @var{duration})
|
|
Packit |
6c4009 |
@standards{POSIX.1, termios.h}
|
|
Packit |
6c4009 |
@safety{@prelim{}@mtunsafe{@mtasurace{:tcattr(filedes)/bsd}}@asunsafe{}@acunsafe{@acucorrupt{/bsd}}}
|
|
Packit |
6c4009 |
@c On Linux, this calls just one out of two ioctls; on BSD, it's two
|
|
Packit |
6c4009 |
@c ioctls with a select (for the delay only) in between, the first
|
|
Packit |
6c4009 |
@c setting and the latter clearing the break status. The BSD
|
|
Packit |
6c4009 |
@c implementation may leave the break enabled if cancelled, and threads
|
|
Packit |
6c4009 |
@c and signals may cause the break to be interrupted before requested.
|
|
Packit |
6c4009 |
This function generates a break condition by transmitting a stream of
|
|
Packit |
6c4009 |
zero bits on the terminal associated with the file descriptor
|
|
Packit |
6c4009 |
@var{filedes}. The duration of the break is controlled by the
|
|
Packit |
6c4009 |
@var{duration} argument. If zero, the duration is between 0.25 and 0.5
|
|
Packit |
6c4009 |
seconds. The meaning of a nonzero value depends on the operating system.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
This function does nothing if the terminal is not an asynchronous serial
|
|
Packit |
6c4009 |
data port.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
The return value is normally zero. In the event of an error, a value
|
|
Packit |
6c4009 |
of @math{-1} is returned. The following @code{errno} error conditions
|
|
Packit |
6c4009 |
are defined for this function:
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@table @code
|
|
Packit |
6c4009 |
@item EBADF
|
|
Packit |
6c4009 |
The @var{filedes} is not a valid file descriptor.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@item ENOTTY
|
|
Packit |
6c4009 |
The @var{filedes} is not associated with a terminal device.
|
|
Packit |
6c4009 |
@end table
|
|
Packit |
6c4009 |
@end deftypefun
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@cindex flushing terminal output queue
|
|
Packit |
6c4009 |
@cindex terminal output queue, flushing
|
|
Packit |
6c4009 |
@deftypefun int tcdrain (int @var{filedes})
|
|
Packit |
6c4009 |
@standards{POSIX.1, termios.h}
|
|
Packit |
6c4009 |
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
|
|
Packit |
6c4009 |
@c Direct ioctl.
|
|
Packit |
6c4009 |
The @code{tcdrain} function waits until all queued
|
|
Packit |
6c4009 |
output to the terminal @var{filedes} has been transmitted.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
This function is a cancellation point in multi-threaded programs. This
|
|
Packit |
6c4009 |
is a problem if the thread allocates some resources (like memory, file
|
|
Packit |
6c4009 |
descriptors, semaphores or whatever) at the time @code{tcdrain} is
|
|
Packit |
6c4009 |
called. If the thread gets canceled these resources stay allocated
|
|
Packit |
6c4009 |
until the program ends. To avoid this calls to @code{tcdrain} should be
|
|
Packit |
6c4009 |
protected using cancellation handlers.
|
|
Packit |
6c4009 |
@c ref pthread_cleanup_push / pthread_cleanup_pop
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
The return value is normally zero. In the event of an error, a value
|
|
Packit |
6c4009 |
of @math{-1} is returned. The following @code{errno} error conditions
|
|
Packit |
6c4009 |
are defined for this function:
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@table @code
|
|
Packit |
6c4009 |
@item EBADF
|
|
Packit |
6c4009 |
The @var{filedes} is not a valid file descriptor.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@item ENOTTY
|
|
Packit |
6c4009 |
The @var{filedes} is not associated with a terminal device.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@item EINTR
|
|
Packit |
6c4009 |
The operation was interrupted by delivery of a signal.
|
|
Packit |
6c4009 |
@xref{Interrupted Primitives}.
|
|
Packit |
6c4009 |
@end table
|
|
Packit |
6c4009 |
@end deftypefun
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@cindex clearing terminal input queue
|
|
Packit |
6c4009 |
@cindex terminal input queue, clearing
|
|
Packit |
6c4009 |
@deftypefun int tcflush (int @var{filedes}, int @var{queue})
|
|
Packit |
6c4009 |
@standards{POSIX.1, termios.h}
|
|
Packit |
6c4009 |
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
|
|
Packit |
6c4009 |
@c Direct ioctl.
|
|
Packit |
6c4009 |
The @code{tcflush} function is used to clear the input and/or output
|
|
Packit |
6c4009 |
queues associated with the terminal file @var{filedes}. The @var{queue}
|
|
Packit |
6c4009 |
argument specifies which queue(s) to clear, and can be one of the
|
|
Packit |
6c4009 |
following values:
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@c Extra blank lines here make it look better.
|
|
Packit |
6c4009 |
@vtable @code
|
|
Packit |
6c4009 |
@item TCIFLUSH
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
Clear any input data received, but not yet read.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@item TCOFLUSH
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
Clear any output data written, but not yet transmitted.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@item TCIOFLUSH
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
Clear both queued input and output.
|
|
Packit |
6c4009 |
@end vtable
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
The return value is normally zero. In the event of an error, a value
|
|
Packit |
6c4009 |
of @math{-1} is returned. The following @code{errno} error conditions
|
|
Packit |
6c4009 |
are defined for this function:
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@table @code
|
|
Packit |
6c4009 |
@item EBADF
|
|
Packit |
6c4009 |
The @var{filedes} is not a valid file descriptor.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@item ENOTTY
|
|
Packit |
6c4009 |
The @var{filedes} is not associated with a terminal device.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@item EINVAL
|
|
Packit |
6c4009 |
A bad value was supplied as the @var{queue} argument.
|
|
Packit |
6c4009 |
@end table
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
It is unfortunate that this function is named @code{tcflush}, because
|
|
Packit |
6c4009 |
the term ``flush'' is normally used for quite another operation---waiting
|
|
Packit |
6c4009 |
until all output is transmitted---and using it for discarding input or
|
|
Packit |
6c4009 |
output would be confusing. Unfortunately, the name @code{tcflush} comes
|
|
Packit |
6c4009 |
from POSIX and we cannot change it.
|
|
Packit |
6c4009 |
@end deftypefun
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@cindex flow control, terminal
|
|
Packit |
6c4009 |
@cindex terminal flow control
|
|
Packit |
6c4009 |
@deftypefun int tcflow (int @var{filedes}, int @var{action})
|
|
Packit |
6c4009 |
@standards{POSIX.1, termios.h}
|
|
Packit |
6c4009 |
@safety{@prelim{}@mtunsafe{@mtasurace{:tcattr(filedes)/bsd}}@asunsafe{}@acsafe{}}
|
|
Packit |
6c4009 |
@c Direct ioctl on Linux. On BSD, the TCO* actions are a single ioctl,
|
|
Packit |
6c4009 |
@c whereas the TCI actions first call tcgetattr and then write to the fd
|
|
Packit |
6c4009 |
@c the c_cc character corresponding to the action; there's a window for
|
|
Packit |
6c4009 |
@c another thread to change the xon/xoff characters.
|
|
Packit |
6c4009 |
The @code{tcflow} function is used to perform operations relating to
|
|
Packit |
6c4009 |
XON/XOFF flow control on the terminal file specified by @var{filedes}.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
The @var{action} argument specifies what operation to perform, and can
|
|
Packit |
6c4009 |
be one of the following values:
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@vtable @code
|
|
Packit |
6c4009 |
@item TCOOFF
|
|
Packit |
6c4009 |
Suspend transmission of output.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@item TCOON
|
|
Packit |
6c4009 |
Restart transmission of output.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@item TCIOFF
|
|
Packit |
6c4009 |
Transmit a STOP character.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@item TCION
|
|
Packit |
6c4009 |
Transmit a START character.
|
|
Packit |
6c4009 |
@end vtable
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
For more information about the STOP and START characters, see @ref{Special
|
|
Packit |
6c4009 |
Characters}.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
The return value is normally zero. In the event of an error, a value
|
|
Packit |
6c4009 |
of @math{-1} is returned. The following @code{errno} error conditions
|
|
Packit |
6c4009 |
are defined for this function:
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@table @code
|
|
Packit |
6c4009 |
@vindex EBADF
|
|
Packit |
6c4009 |
@item EBADF
|
|
Packit |
6c4009 |
The @var{filedes} is not a valid file descriptor.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@vindex ENOTTY
|
|
Packit |
6c4009 |
@item ENOTTY
|
|
Packit |
6c4009 |
The @var{filedes} is not associated with a terminal device.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@vindex EINVAL
|
|
Packit |
6c4009 |
@item EINVAL
|
|
Packit |
6c4009 |
A bad value was supplied as the @var{action} argument.
|
|
Packit |
6c4009 |
@end table
|
|
Packit |
6c4009 |
@end deftypefun
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@node Noncanon Example
|
|
Packit |
6c4009 |
@section Noncanonical Mode Example
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
Here is an example program that shows how you can set up a terminal
|
|
Packit |
6c4009 |
device to read single characters in noncanonical input mode, without
|
|
Packit |
6c4009 |
echo.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@smallexample
|
|
Packit |
6c4009 |
@include termios.c.texi
|
|
Packit |
6c4009 |
@end smallexample
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
This program is careful to restore the original terminal modes before
|
|
Packit |
6c4009 |
exiting or terminating with a signal. It uses the @code{atexit}
|
|
Packit |
6c4009 |
function (@pxref{Cleanups on Exit}) to make sure this is done
|
|
Packit |
6c4009 |
by @code{exit}.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@ignore
|
|
Packit |
6c4009 |
@c !!!! the example doesn't handle any signals!
|
|
Packit |
6c4009 |
The signals handled in the example are the ones that typically occur due
|
|
Packit |
6c4009 |
to actions of the user. It might be desirable to handle other signals
|
|
Packit |
6c4009 |
such as SIGSEGV that can result from bugs in the program.
|
|
Packit |
6c4009 |
@end ignore
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
The shell is supposed to take care of resetting the terminal modes when
|
|
Packit |
6c4009 |
a process is stopped or continued; see @ref{Job Control}. But some
|
|
Packit |
6c4009 |
existing shells do not actually do this, so you may wish to establish
|
|
Packit |
6c4009 |
handlers for job control signals that reset terminal modes. The above
|
|
Packit |
6c4009 |
example does so.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@node getpass
|
|
Packit |
6c4009 |
@section Reading Passphrases
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
When reading in a passphrase, it is desirable to avoid displaying it on
|
|
Packit |
6c4009 |
the screen, to help keep it secret. The following function handles this
|
|
Packit |
6c4009 |
in a convenient way.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@deftypefun {char *} getpass (const char *@var{prompt})
|
|
Packit |
6c4009 |
@standards{BSD, unistd.h}
|
|
Packit |
6c4009 |
@safety{@prelim{}@mtunsafe{@mtasuterm{}}@asunsafe{@ascuheap{} @asulock{} @asucorrupt{}}@acunsafe{@acuterm{} @aculock{} @acucorrupt{}}}
|
|
Packit |
6c4009 |
@c This function will attempt to create a stream for terminal I/O, but
|
|
Packit |
6c4009 |
@c will fallback to stdio/stderr. It attempts to change the terminal
|
|
Packit |
6c4009 |
@c mode in a thread-unsafe way, write out the prompt, read the passphrase,
|
|
Packit |
6c4009 |
@c then restore the terminal mode. It has a cleanup to close the stream
|
|
Packit |
6c4009 |
@c in case of (synchronous) cancellation, but not to restore the
|
|
Packit |
6c4009 |
@c terminal mode.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@code{getpass} outputs @var{prompt}, then reads a string in from the
|
|
Packit |
6c4009 |
terminal without echoing it. It tries to connect to the real terminal,
|
|
Packit |
6c4009 |
@file{/dev/tty}, if possible, to encourage users not to put plaintext
|
|
Packit |
6c4009 |
passphrases in files; otherwise, it uses @code{stdin} and @code{stderr}.
|
|
Packit |
6c4009 |
@code{getpass} also disables the INTR, QUIT, and SUSP characters on the
|
|
Packit |
6c4009 |
terminal using the @code{ISIG} terminal attribute (@pxref{Local Modes}).
|
|
Packit |
6c4009 |
The terminal is flushed before and after @code{getpass}, so that
|
|
Packit |
6c4009 |
characters of a mistyped passphrase are not accidentally visible.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
In other C libraries, @code{getpass} may only return the first
|
|
Packit |
6c4009 |
@code{PASS_MAX} bytes of a passphrase. @Theglibc{} has no limit, so
|
|
Packit |
6c4009 |
@code{PASS_MAX} is undefined.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
The prototype for this function is in @file{unistd.h}. @code{PASS_MAX}
|
|
Packit |
6c4009 |
would be defined in @file{limits.h}.
|
|
Packit |
6c4009 |
@end deftypefun
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
This precise set of operations may not suit all possible situations. In
|
|
Packit |
6c4009 |
this case, it is recommended that users write their own @code{getpass}
|
|
Packit |
6c4009 |
substitute. For instance, a very simple substitute is as follows:
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@smallexample
|
|
Packit |
6c4009 |
@include mygetpass.c.texi
|
|
Packit |
6c4009 |
@end smallexample
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
The substitute takes the same parameters as @code{getline}
|
|
Packit |
6c4009 |
(@pxref{Line Input}); the user must print any prompt desired.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@node Pseudo-Terminals
|
|
Packit |
6c4009 |
@section Pseudo-Terminals
|
|
Packit |
6c4009 |
@cindex pseudo-terminals
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
A @dfn{pseudo-terminal} is a special interprocess communication channel
|
|
Packit |
6c4009 |
that acts like a terminal. One end of the channel is called the
|
|
Packit |
6c4009 |
@dfn{master} side or @dfn{master pseudo-terminal device}, the other side
|
|
Packit |
6c4009 |
is called the @dfn{slave} side. Data written to the master side is
|
|
Packit |
6c4009 |
received by the slave side as if it was the result of a user typing at
|
|
Packit |
6c4009 |
an ordinary terminal, and data written to the slave side is sent to the
|
|
Packit |
6c4009 |
master side as if it was written on an ordinary terminal.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
Pseudo terminals are the way programs like @code{xterm} and @code{emacs}
|
|
Packit |
6c4009 |
implement their terminal emulation functionality.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@menu
|
|
Packit |
6c4009 |
* Allocation:: Allocating a pseudo terminal.
|
|
Packit |
6c4009 |
* Pseudo-Terminal Pairs:: How to open both sides of a
|
|
Packit |
6c4009 |
pseudo-terminal in a single operation.
|
|
Packit |
6c4009 |
@end menu
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@node Allocation
|
|
Packit |
6c4009 |
@subsection Allocating Pseudo-Terminals
|
|
Packit |
6c4009 |
@cindex allocating pseudo-terminals
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@pindex stdlib.h
|
|
Packit |
6c4009 |
This subsection describes functions for allocating a pseudo-terminal,
|
|
Packit |
6c4009 |
and for making this pseudo-terminal available for actual use. These
|
|
Packit |
6c4009 |
functions are declared in the header file @file{stdlib.h}.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@deftypefun int getpt (void)
|
|
Packit |
6c4009 |
@standards{GNU, stdlib.h}
|
|
Packit |
6c4009 |
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{@acsfd{}}}
|
|
Packit |
6c4009 |
@c On BSD, tries to open multiple potential pty names, returning on the
|
|
Packit |
6c4009 |
@c first success. On Linux, try posix_openpt first, then fallback to
|
|
Packit |
6c4009 |
@c the BSD implementation. The posix implementation opens the ptmx
|
|
Packit |
6c4009 |
@c device, checks with statfs that /dev/pts is a devpts or that /dev is
|
|
Packit |
6c4009 |
@c a devfs, and returns the fd; static variables devpts_mounted and
|
|
Packit |
6c4009 |
@c have_no_dev_ptmx are safely initialized so as to avoid repeated
|
|
Packit |
6c4009 |
@c tests.
|
|
Packit |
6c4009 |
The @code{getpt} function returns a new file descriptor for the next
|
|
Packit |
6c4009 |
available master pseudo-terminal. The normal return value from
|
|
Packit |
6c4009 |
@code{getpt} is a non-negative integer file descriptor. In the case of
|
|
Packit |
6c4009 |
an error, a value of @math{-1} is returned instead. The following
|
|
Packit |
6c4009 |
@code{errno} conditions are defined for this function:
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@table @code
|
|
Packit |
6c4009 |
@item ENOENT
|
|
Packit |
6c4009 |
There are no free master pseudo-terminals available.
|
|
Packit |
6c4009 |
@end table
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
This function is a GNU extension.
|
|
Packit |
6c4009 |
@end deftypefun
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@deftypefun int grantpt (int @var{filedes})
|
|
Packit |
6c4009 |
@standards{SVID, stdlib.h}
|
|
Packit |
6c4009 |
@standards{XPG4.2, stdlib.h}
|
|
Packit |
6c4009 |
@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
|
|
Packit |
6c4009 |
@c grantpt @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
|
|
Packit |
6c4009 |
@c unix/grantpt:pts_name @acsuheap @acsmem
|
|
Packit |
6c4009 |
@c ptsname_internal dup ok (but this is Linux-only!)
|
|
Packit |
6c4009 |
@c memchr dup ok
|
|
Packit |
6c4009 |
@c realloc dup @acsuheap @acsmem
|
|
Packit |
6c4009 |
@c malloc dup @acsuheap @acsmem
|
|
Packit |
6c4009 |
@c free dup @acsuheap @acsmem
|
|
Packit |
6c4009 |
@c fcntl dup ok
|
|
Packit |
6c4009 |
@c getuid dup ok
|
|
Packit |
6c4009 |
@c chown dup ok
|
|
Packit |
6c4009 |
@c sysconf(_SC_GETGR_R_SIZE_MAX) ok
|
|
Packit |
6c4009 |
@c getgrnam_r @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
|
|
Packit |
6c4009 |
@c getgid dup ok
|
|
Packit |
6c4009 |
@c chmod dup ok
|
|
Packit |
6c4009 |
@c fork dup @aculock
|
|
Packit |
6c4009 |
@c [child]
|
|
Packit |
6c4009 |
@c setrlimit
|
|
Packit |
6c4009 |
@c dup2
|
|
Packit |
6c4009 |
@c CLOSE_ALL_FDS
|
|
Packit |
6c4009 |
@c execle
|
|
Packit |
6c4009 |
@c _exit
|
|
Packit |
6c4009 |
@c waitpid dup ok
|
|
Packit |
6c4009 |
@c WIFEXITED dup ok
|
|
Packit |
6c4009 |
@c WEXITSTATUS dup ok
|
|
Packit |
6c4009 |
@c free dup @ascuheap @acsmem
|
|
Packit |
6c4009 |
The @code{grantpt} function changes the ownership and access permission
|
|
Packit |
6c4009 |
of the slave pseudo-terminal device corresponding to the master
|
|
Packit |
6c4009 |
pseudo-terminal device associated with the file descriptor
|
|
Packit |
6c4009 |
@var{filedes}. The owner is set from the real user ID of the calling
|
|
Packit |
6c4009 |
process (@pxref{Process Persona}), and the group is set to a special
|
|
Packit |
6c4009 |
group (typically @dfn{tty}) or from the real group ID of the calling
|
|
Packit |
6c4009 |
process. The access permission is set such that the file is both
|
|
Packit |
6c4009 |
readable and writable by the owner and only writable by the group.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
On some systems this function is implemented by invoking a special
|
|
Packit |
6c4009 |
@code{setuid} root program (@pxref{How Change Persona}). As a
|
|
Packit |
6c4009 |
consequence, installing a signal handler for the @code{SIGCHLD} signal
|
|
Packit |
6c4009 |
(@pxref{Job Control Signals}) may interfere with a call to
|
|
Packit |
6c4009 |
@code{grantpt}.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
The normal return value from @code{grantpt} is @math{0}; a value of
|
|
Packit |
6c4009 |
@math{-1} is returned in case of failure. The following @code{errno}
|
|
Packit |
6c4009 |
error conditions are defined for this function:
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@table @code
|
|
Packit |
6c4009 |
@item EBADF
|
|
Packit |
6c4009 |
The @var{filedes} argument is not a valid file descriptor.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@item EINVAL
|
|
Packit |
6c4009 |
The @var{filedes} argument is not associated with a master pseudo-terminal
|
|
Packit |
6c4009 |
device.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@item EACCES
|
|
Packit |
6c4009 |
The slave pseudo-terminal device corresponding to the master associated
|
|
Packit |
6c4009 |
with @var{filedes} could not be accessed.
|
|
Packit |
6c4009 |
@end table
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@end deftypefun
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@deftypefun int unlockpt (int @var{filedes})
|
|
Packit |
6c4009 |
@standards{SVID, stdlib.h}
|
|
Packit |
6c4009 |
@standards{XPG4.2, stdlib.h}
|
|
Packit |
6c4009 |
@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{/bsd}}@acunsafe{@acsmem{} @acsfd{}}}
|
|
Packit |
6c4009 |
@c unlockpt @ascuheap/bsd @acsmem @acsfd
|
|
Packit |
6c4009 |
@c /bsd
|
|
Packit |
6c4009 |
@c ptsname_r dup @ascuheap @acsmem @acsfd
|
|
Packit |
6c4009 |
@c revoke ok (syscall)
|
|
Packit |
6c4009 |
@c /linux
|
|
Packit |
6c4009 |
@c ioctl dup ok
|
|
Packit |
6c4009 |
The @code{unlockpt} function unlocks the slave pseudo-terminal device
|
|
Packit |
6c4009 |
corresponding to the master pseudo-terminal device associated with the
|
|
Packit |
6c4009 |
file descriptor @var{filedes}. On many systems, the slave can only be
|
|
Packit |
6c4009 |
opened after unlocking, so portable applications should always call
|
|
Packit |
6c4009 |
@code{unlockpt} before trying to open the slave.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
The normal return value from @code{unlockpt} is @math{0}; a value of
|
|
Packit |
6c4009 |
@math{-1} is returned in case of failure. The following @code{errno}
|
|
Packit |
6c4009 |
error conditions are defined for this function:
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@table @code
|
|
Packit |
6c4009 |
@item EBADF
|
|
Packit |
6c4009 |
The @var{filedes} argument is not a valid file descriptor.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@item EINVAL
|
|
Packit |
6c4009 |
The @var{filedes} argument is not associated with a master pseudo-terminal
|
|
Packit |
6c4009 |
device.
|
|
Packit |
6c4009 |
@end table
|
|
Packit |
6c4009 |
@end deftypefun
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@deftypefun {char *} ptsname (int @var{filedes})
|
|
Packit |
6c4009 |
@standards{SVID, stdlib.h}
|
|
Packit |
6c4009 |
@standards{XPG4.2, stdlib.h}
|
|
Packit |
6c4009 |
@safety{@prelim{}@mtunsafe{@mtasurace{:ptsname}}@asunsafe{@ascuheap{/bsd}}@acunsafe{@acsmem{} @acsfd{}}}
|
|
Packit |
6c4009 |
@c ptsname @mtasurace:ptsname @ascuheap/bsd @acsmem @acsfd
|
|
Packit |
6c4009 |
@c ptsname_r dup @ascuheap/bsd @acsmem @acsfd
|
|
Packit |
6c4009 |
If the file descriptor @var{filedes} is associated with a
|
|
Packit |
6c4009 |
master pseudo-terminal device, the @code{ptsname} function returns a
|
|
Packit |
6c4009 |
pointer to a statically-allocated, null-terminated string containing the
|
|
Packit |
6c4009 |
file name of the associated slave pseudo-terminal file. This string
|
|
Packit |
6c4009 |
might be overwritten by subsequent calls to @code{ptsname}.
|
|
Packit |
6c4009 |
@end deftypefun
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@deftypefun int ptsname_r (int @var{filedes}, char *@var{buf}, size_t @var{len})
|
|
Packit |
6c4009 |
@standards{GNU, stdlib.h}
|
|
Packit |
6c4009 |
@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{/bsd}}@acunsafe{@acsmem{} @acsfd{}}}
|
|
Packit |
6c4009 |
@c ptsname_r @ascuheap/bsd @acsmem @acsfd
|
|
Packit |
6c4009 |
@c /hurd
|
|
Packit |
6c4009 |
@c term_get_peername ok
|
|
Packit |
6c4009 |
@c strlen dup ok
|
|
Packit |
6c4009 |
@c memcpy dup ok
|
|
Packit |
6c4009 |
@c /bsd
|
|
Packit |
6c4009 |
@c isatty dup ok
|
|
Packit |
6c4009 |
@c strlen dup ok
|
|
Packit |
6c4009 |
@c ttyname_r dup @ascuheap @acsmem @acsfd
|
|
Packit |
6c4009 |
@c stat dup ok
|
|
Packit |
6c4009 |
@c /linux
|
|
Packit |
6c4009 |
@c ptsname_internal ok
|
|
Packit |
6c4009 |
@c isatty dup ok
|
|
Packit |
6c4009 |
@c ioctl dup ok
|
|
Packit |
6c4009 |
@c strlen dup ok
|
|
Packit |
6c4009 |
@c itoa_word dup ok
|
|
Packit |
6c4009 |
@c stpcpy dup ok
|
|
Packit |
6c4009 |
@c memcpy dup ok
|
|
Packit |
6c4009 |
@c fxstat64 dup ok
|
|
Packit |
6c4009 |
@c MASTER_P ok
|
|
Packit |
6c4009 |
@c major ok
|
|
Packit |
6c4009 |
@c gnu_dev_major ok
|
|
Packit |
6c4009 |
@c minor ok
|
|
Packit |
6c4009 |
@c gnu_dev_minor ok
|
|
Packit |
6c4009 |
@c minor dup ok
|
|
Packit |
6c4009 |
@c xstat64 dup ok
|
|
Packit |
6c4009 |
@c S_ISCHR dup ok
|
|
Packit |
6c4009 |
@c SLAVE_P ok
|
|
Packit |
6c4009 |
@c major dup ok
|
|
Packit |
6c4009 |
@c minor dup ok
|
|
Packit |
6c4009 |
The @code{ptsname_r} function is similar to the @code{ptsname} function
|
|
Packit |
6c4009 |
except that it places its result into the user-specified buffer starting
|
|
Packit |
6c4009 |
at @var{buf} with length @var{len}.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
This function is a GNU extension.
|
|
Packit |
6c4009 |
@end deftypefun
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@strong{Portability Note:} On @w{System V} derived systems, the file
|
|
Packit |
6c4009 |
returned by the @code{ptsname} and @code{ptsname_r} functions may be
|
|
Packit |
6c4009 |
STREAMS-based, and therefore require additional processing after opening
|
|
Packit |
6c4009 |
before it actually behaves as a pseudo terminal.
|
|
Packit |
6c4009 |
@c FIXME: xref STREAMS
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
Typical usage of these functions is illustrated by the following example:
|
|
Packit |
6c4009 |
@smallexample
|
|
Packit |
6c4009 |
int
|
|
Packit |
6c4009 |
open_pty_pair (int *amaster, int *aslave)
|
|
Packit |
6c4009 |
@{
|
|
Packit |
6c4009 |
int master, slave;
|
|
Packit |
6c4009 |
char *name;
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
master = getpt ();
|
|
Packit |
6c4009 |
if (master < 0)
|
|
Packit |
6c4009 |
return 0;
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
if (grantpt (master) < 0 || unlockpt (master) < 0)
|
|
Packit |
6c4009 |
goto close_master;
|
|
Packit |
6c4009 |
name = ptsname (master);
|
|
Packit |
6c4009 |
if (name == NULL)
|
|
Packit |
6c4009 |
goto close_master;
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
slave = open (name, O_RDWR);
|
|
Packit |
6c4009 |
if (slave == -1)
|
|
Packit |
6c4009 |
goto close_master;
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
if (isastream (slave))
|
|
Packit |
6c4009 |
@{
|
|
Packit |
6c4009 |
if (ioctl (slave, I_PUSH, "ptem") < 0
|
|
Packit |
6c4009 |
|| ioctl (slave, I_PUSH, "ldterm") < 0)
|
|
Packit |
6c4009 |
goto close_slave;
|
|
Packit |
6c4009 |
@}
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
*amaster = master;
|
|
Packit |
6c4009 |
*aslave = slave;
|
|
Packit |
6c4009 |
return 1;
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
close_slave:
|
|
Packit |
6c4009 |
close (slave);
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
close_master:
|
|
Packit |
6c4009 |
close (master);
|
|
Packit |
6c4009 |
return 0;
|
|
Packit |
6c4009 |
@}
|
|
Packit |
6c4009 |
@end smallexample
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@node Pseudo-Terminal Pairs
|
|
Packit |
6c4009 |
@subsection Opening a Pseudo-Terminal Pair
|
|
Packit |
6c4009 |
@cindex opening a pseudo-terminal pair
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
These functions, derived from BSD, are available in the separate
|
|
Packit |
6c4009 |
@file{libutil} library, and declared in @file{pty.h}.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@deftypefun int openpty (int *@var{amaster}, int *@var{aslave}, char *@var{name}, const struct termios *@var{termp}, const struct winsize *@var{winp})
|
|
Packit |
6c4009 |
@standards{BSD, pty.h}
|
|
Packit |
6c4009 |
@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
|
|
Packit |
6c4009 |
@c openpty @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
|
|
Packit |
6c4009 |
@c getpt @acsfd
|
|
Packit |
6c4009 |
@c grantpt @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
|
|
Packit |
6c4009 |
@c unlockpt dup @ascuheap/bsd @acsmem @acsfd
|
|
Packit |
6c4009 |
@c openpty:pts_name @acsuheap @acsmem @acsfd
|
|
Packit |
6c4009 |
@c ptsname_r dup @ascuheap/bsd @acsmem @acsfd
|
|
Packit |
6c4009 |
@c realloc dup @acsuheap @acsmem
|
|
Packit |
6c4009 |
@c malloc dup @acsuheap @acsmem
|
|
Packit |
6c4009 |
@c free dup @acsuheap @acsmem
|
|
Packit |
6c4009 |
@c open dup @acsfd
|
|
Packit |
6c4009 |
@c free dup @acsuheap @acsmem
|
|
Packit |
6c4009 |
@c tcsetattr dup ok
|
|
Packit |
6c4009 |
@c ioctl dup ok
|
|
Packit |
6c4009 |
@c strcpy dup ok
|
|
Packit |
6c4009 |
@c close dup @acsfd
|
|
Packit |
6c4009 |
This function allocates and opens a pseudo-terminal pair, returning the
|
|
Packit |
6c4009 |
file descriptor for the master in @var{*amaster}, and the file
|
|
Packit |
6c4009 |
descriptor for the slave in @var{*aslave}. If the argument @var{name}
|
|
Packit |
6c4009 |
is not a null pointer, the file name of the slave pseudo-terminal
|
|
Packit |
6c4009 |
device is stored in @code{*name}. If @var{termp} is not a null pointer,
|
|
Packit |
6c4009 |
the terminal attributes of the slave are set to the ones specified in
|
|
Packit |
6c4009 |
the structure that @var{termp} points to (@pxref{Terminal Modes}).
|
|
Packit |
6c4009 |
Likewise, if @var{winp} is not a null pointer, the screen size of
|
|
Packit |
6c4009 |
the slave is set to the values specified in the structure that
|
|
Packit |
6c4009 |
@var{winp} points to.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
The normal return value from @code{openpty} is @math{0}; a value of
|
|
Packit |
6c4009 |
@math{-1} is returned in case of failure. The following @code{errno}
|
|
Packit |
6c4009 |
conditions are defined for this function:
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@table @code
|
|
Packit |
6c4009 |
@item ENOENT
|
|
Packit |
6c4009 |
There are no free pseudo-terminal pairs available.
|
|
Packit |
6c4009 |
@end table
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@strong{Warning:} Using the @code{openpty} function with @var{name} not
|
|
Packit |
6c4009 |
set to @code{NULL} is @strong{very dangerous} because it provides no
|
|
Packit |
6c4009 |
protection against overflowing the string @var{name}. You should use
|
|
Packit |
6c4009 |
the @code{ttyname} function on the file descriptor returned in
|
|
Packit |
6c4009 |
@var{*slave} to find out the file name of the slave pseudo-terminal
|
|
Packit |
6c4009 |
device instead.
|
|
Packit |
6c4009 |
@end deftypefun
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@deftypefun int forkpty (int *@var{amaster}, char *@var{name}, const struct termios *@var{termp}, const struct winsize *@var{winp})
|
|
Packit |
6c4009 |
@standards{BSD, pty.h}
|
|
Packit |
6c4009 |
@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
|
|
Packit |
6c4009 |
@c forkpty @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
|
|
Packit |
6c4009 |
@c openpty dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
|
|
Packit |
6c4009 |
@c fork dup @aculock
|
|
Packit |
6c4009 |
@c close dup @acsfd
|
|
Packit |
6c4009 |
@c /child
|
|
Packit |
6c4009 |
@c close dup @acsfd
|
|
Packit |
6c4009 |
@c login_tty dup @mtasurace:ttyname @ascuheap @asulock @aculock @acsmem @acsfd
|
|
Packit |
6c4009 |
@c _exit dup ok
|
|
Packit |
6c4009 |
@c close dup @acsfd
|
|
Packit |
6c4009 |
This function is similar to the @code{openpty} function, but in
|
|
Packit |
6c4009 |
addition, forks a new process (@pxref{Creating a Process}) and makes the
|
|
Packit |
6c4009 |
newly opened slave pseudo-terminal device the controlling terminal
|
|
Packit |
6c4009 |
(@pxref{Controlling Terminal}) for the child process.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
If the operation is successful, there are then both parent and child
|
|
Packit |
6c4009 |
processes and both see @code{forkpty} return, but with different values:
|
|
Packit |
6c4009 |
it returns a value of @math{0} in the child process and returns the child's
|
|
Packit |
6c4009 |
process ID in the parent process.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
If the allocation of a pseudo-terminal pair or the process creation
|
|
Packit |
6c4009 |
failed, @code{forkpty} returns a value of @math{-1} in the parent
|
|
Packit |
6c4009 |
process.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@strong{Warning:} The @code{forkpty} function has the same problems with
|
|
Packit |
6c4009 |
respect to the @var{name} argument as @code{openpty}.
|
|
Packit |
6c4009 |
@end deftypefun
|