@node Low-Level Terminal Interface, Syslog, Sockets, Top

@c %MENU% How to change the characteristics of a terminal device

@chapter Low-Level Terminal Interface

This chapter describes functions that are specific to terminal devices.

You can use these functions to do things like turn off input echoing;

set serial line characteristics such as line speed and flow control; and

change which characters are used for end-of-file, command-line editing,

sending signals, and similar control functions.

Most of the functions in this chapter operate on file descriptors.

@xref{Low-Level I/O}, for more information about what a file

descriptor is and how to open a file descriptor for a terminal device.

@menu

* Is It a Terminal::            How to determine if a file is a terminal

			         device, and what its name is.

* I/O Queues::                  About flow control and typeahead.

* Canonical or Not::            Two basic styles of input processing.

* Terminal Modes::              How to examine and modify flags controlling

			         details of terminal I/O: echoing,

                                 signals, editing.  Posix.

* BSD Terminal Modes::          BSD compatible terminal mode setting

* Line Control::                Sending break sequences, clearing

                                 terminal buffers @dots{}

* Noncanon Example::            How to read single characters without echo.

* getpass::                     Prompting the user for a passphrase.

* Pseudo-Terminals::            How to open a pseudo-terminal.

@end menu

@node Is It a Terminal

@section Identifying Terminals

@cindex terminal identification

@cindex identifying terminals

The functions described in this chapter only work on files that

correspond to terminal devices.  You can find out whether a file

descriptor is associated with a terminal by using the @code{isatty}

function.

@pindex unistd.h

Prototypes for the functions in this section are declared in the header

file @file{unistd.h}.

@deftypefun int isatty (int @var{filedes})

@standards{POSIX.1, unistd.h}

@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}

@c isatty ok

@c  tcgetattr dup ok

This function returns @code{1} if @var{filedes} is a file descriptor

associated with an open terminal device, and @math{0} otherwise.

@end deftypefun

If a file descriptor is associated with a terminal, you can get its

associated file name using the @code{ttyname} function.  See also the

@code{ctermid} function, described in @ref{Identifying the Terminal}.

@deftypefun {char *} ttyname (int @var{filedes})

@standards{POSIX.1, unistd.h}

@safety{@prelim{}@mtunsafe{@mtasurace{:ttyname}}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsfd{} @acsmem{}}}

@c ttyname @mtasurace:ttyname @ascuheap @asulock @aculock @acsmem @acsfd

@c  isatty dup ok

@c  fstat dup ok

@c  memcpy dup ok

@c  getttyname @mtasurace:ttyname @ascuheap @asulock @aculock @acsmem @acsfd

@c   opendir @ascuheap @acsmem @acsfd

@c   readdir ok [protected by exclusive access]

@c   strcmp dup ok

@c   free dup @asulock @aculock @acsfd @acsmem

@c   malloc dup @asulock @aculock @acsfd @acsmem

@c   closedir @ascuheap @acsmem @acsfd

@c   mempcpy dup ok

@c   stat dup ok

If the file descriptor @var{filedes} is associated with a terminal

device, the @code{ttyname} function returns a pointer to a

statically-allocated, null-terminated string containing the file name of

the terminal file.  The value is a null pointer if the file descriptor

isn't associated with a terminal, or the file name cannot be determined.

@end deftypefun

@deftypefun int ttyname_r (int @var{filedes}, char *@var{buf}, size_t @var{len})

@standards{POSIX.1, unistd.h}

@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{} @acsfd{}}}

@c ttyname_r @ascuheap @acsmem @acsfd

@c  isatty dup ok

@c  fstat dup ok

@c  memcpy dup ok

@c  getttyname_r @ascuheap @acsmem @acsfd

@c   opendir @ascuheap @acsmem @acsfd

@c   readdir ok [protected by exclusive access]

@c   strcmp dup ok

@c   closedir @ascuheap @acsmem @acsfd

@c   stpncpy dup ok

@c   stat dup ok

The @code{ttyname_r} function is similar to the @code{ttyname} function

except that it places its result into the user-specified buffer starting

at @var{buf} with length @var{len}.

The normal return value from @code{ttyname_r} is @math{0}.  Otherwise an

error number is returned to indicate the error.  The following

@code{errno} error conditions are defined for this function:

@table @code

@item EBADF

The @var{filedes} argument is not a valid file descriptor.

@item ENOTTY

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

@item ERANGE

The buffer length @var{len} is too small to store the string to be

returned.

@item ENODEV

The @var{filedes} is associated with a terminal device that is a slave

pseudo-terminal, but the file name associated with that device could

not be determined.  This is a GNU extension.

@end table

@end deftypefun

@node I/O Queues

@section I/O Queues

Many of the remaining functions in this section refer to the input and

output queues of a terminal device.  These queues implement a form of

buffering @emph{within the kernel} independent of the buffering

implemented by I/O streams (@pxref{I/O on Streams}).

@cindex terminal input queue

@cindex typeahead buffer

The @dfn{terminal input queue} is also sometimes referred to as its

@dfn{typeahead buffer}.  It holds the characters that have been received

from the terminal but not yet read by any process.

The size of the input queue is described by the @code{MAX_INPUT} and

@w{@code{_POSIX_MAX_INPUT}} parameters; see @ref{Limits for Files}.  You

are guaranteed a queue size of at least @code{MAX_INPUT}, but the queue

might be larger, and might even dynamically change size.  If input flow

control is enabled by setting the @code{IXOFF} input mode bit

(@pxref{Input Modes}), the terminal driver transmits STOP and START

characters to the terminal when necessary to prevent the queue from

overflowing.  Otherwise, input may be lost if it comes in too fast from

the terminal.  In canonical mode, all input stays in the queue until a

newline character is received, so the terminal input queue can fill up

when you type a very long line.  @xref{Canonical or Not}.

@cindex terminal output queue

The @dfn{terminal output queue} is like the input queue, but for output;

it contains characters that have been written by processes, but not yet

transmitted to the terminal.  If output flow control is enabled by

setting the @code{IXON} input mode bit (@pxref{Input Modes}), the

terminal driver obeys START and STOP characters sent by the terminal to

stop and restart transmission of output.

@dfn{Clearing} the terminal input queue means discarding any characters

that have been received but not yet read.  Similarly, clearing the

terminal output queue means discarding any characters that have been

written but not yet transmitted.

@node Canonical or Not

@section Two Styles of Input: Canonical or Not

POSIX systems support two basic modes of input: canonical and

noncanonical.

@cindex canonical input processing

In @dfn{canonical input processing} mode, terminal input is processed in

lines terminated by newline (@code{'\n'}), EOF, or EOL characters.  No

input can be read until an entire line has been typed by the user, and

the @code{read} function (@pxref{I/O Primitives}) returns at most a

single line of input, no matter how many bytes are requested.

In canonical input mode, the operating system provides input editing

facilities: some characters are interpreted specially to perform editing

operations within the current line of text, such as ERASE and KILL.

@xref{Editing Characters}.

The constants @code{_POSIX_MAX_CANON} and @code{MAX_CANON} parameterize

the maximum number of bytes which may appear in a single line of

canonical input.  @xref{Limits for Files}.  You are guaranteed a maximum

line length of at least @code{MAX_CANON} bytes, but the maximum might be

larger, and might even dynamically change size.

@cindex noncanonical input processing

In @dfn{noncanonical input processing} mode, characters are not grouped

into lines, and ERASE and KILL processing is not performed.  The

granularity with which bytes are read in noncanonical input mode is

controlled by the MIN and TIME settings.  @xref{Noncanonical Input}.

Most programs use canonical input mode, because this gives the user a

way to edit input line by line.  The usual reason to use noncanonical

mode is when the program accepts single-character commands or provides

its own editing facilities.

The choice of canonical or noncanonical input is controlled by the

@code{ICANON} flag in the @code{c_lflag} member of @code{struct termios}.

@xref{Local Modes}.

@node Terminal Modes

@section Terminal Modes

@pindex termios.h

This section describes the various terminal attributes that control how

input and output are done.  The functions, data structures, and symbolic

constants are all declared in the header file @file{termios.h}.

Don't confuse terminal attributes with file attributes.  A device special

file which is associated with a terminal has file attributes as described

in @ref{File Attributes}.  These are unrelated to the attributes of the

terminal device itself, which are discussed in this section.

@menu

* Mode Data Types::             The data type @code{struct termios} and

                                 related types.

* Mode Functions::              Functions to read and set the terminal

                                 attributes.

* Setting Modes::               The right way to set terminal attributes

                                 reliably.

* Input Modes::                 Flags controlling low-level input handling.

* Output Modes::                Flags controlling low-level output handling.

* Control Modes::               Flags controlling serial port behavior.

* Local Modes::                 Flags controlling high-level input handling.

* Line Speed::                  How to read and set the terminal line speed.

* Special Characters::          Characters that have special effects,

			         and how to change them.

* Noncanonical Input::          Controlling how long to wait for input.

@end menu

@node Mode Data Types

@subsection Terminal Mode Data Types

@cindex terminal mode data types

The entire collection of attributes of a terminal is stored in a

structure of type @code{struct termios}.  This structure is used

with the functions @code{tcgetattr} and @code{tcsetattr} to read

and set the attributes.

@deftp {Data Type} {struct termios}

@standards{POSIX.1, termios.h}

A @code{struct termios} records all the I/O attributes of a terminal.  The

structure includes at least the following members:

@table @code

@item tcflag_t c_iflag

A bit mask specifying flags for input modes; see @ref{Input Modes}.

@item tcflag_t c_oflag

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

@item tcflag_t c_cflag

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

@item tcflag_t c_lflag

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

@item cc_t c_cc[NCCS]

An array specifying which characters are associated with various

control functions; see @ref{Special Characters}.

@end table

The @code{struct termios} structure also contains members which

encode input and output transmission speeds, but the representation is

not specified.  @xref{Line Speed}, for how to examine and store the

speed values.

@end deftp

The following sections describe the details of the members of the

@code{struct termios} structure.

@deftp {Data Type} tcflag_t

@standards{POSIX.1, termios.h}

This is an unsigned integer type used to represent the various

bit masks for terminal flags.

@end deftp

@deftp {Data Type} cc_t

@standards{POSIX.1, termios.h}

This is an unsigned integer type used to represent characters associated

with various terminal control functions.

@end deftp

@deftypevr Macro int NCCS

@standards{POSIX.1, termios.h}

The value of this macro is the number of elements in the @code{c_cc}

array.

@end deftypevr

@node Mode Functions

@subsection Terminal Mode Functions

@cindex terminal mode functions

@deftypefun int tcgetattr (int @var{filedes}, struct termios *@var{termios-p})

@standards{POSIX.1, termios.h}

@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}

@c Converting the kernel-returned termios data structure to the userland

@c format does not ensure atomic or consistent writing.

This function is used to examine the attributes of the terminal

device with file descriptor @var{filedes}.  The attributes are returned

in the structure that @var{termios-p} points to.

If successful, @code{tcgetattr} returns @math{0}.  A return value of @math{-1}

indicates an error.  The following @code{errno} error conditions are

defined for this function:

@table @code

@item EBADF

The @var{filedes} argument is not a valid file descriptor.

@item ENOTTY

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

@end table

@end deftypefun

@deftypefun int tcsetattr (int @var{filedes}, int @var{when}, const struct termios *@var{termios-p})

@standards{POSIX.1, termios.h}

@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}

@c Converting the incoming termios data structure to the kernel format

@c does not ensure atomic or consistent reading.

This function sets the attributes of the terminal device with file

descriptor @var{filedes}.  The new attributes are taken from the

structure that @var{termios-p} points to.

The @var{when} argument specifies how to deal with input and output

already queued.  It can be one of the following values:

@vtable @code

@item TCSANOW

@standards{POSIX.1, termios.h}

Make the change immediately.

@item TCSADRAIN

@standards{POSIX.1, termios.h}

Make the change after waiting until all queued output has been written.

You should usually use this option when changing parameters that affect

output.

@item TCSAFLUSH

@standards{POSIX.1, termios.h}

This is like @code{TCSADRAIN}, but also discards any queued input.

@item TCSASOFT

@standards{BSD, termios.h}

This is a flag bit that you can add to any of the above alternatives.

Its meaning is to inhibit alteration of the state of the terminal

hardware.  It is a BSD extension; it is only supported on BSD systems

and @gnuhurdsystems{}.

Using @code{TCSASOFT} is exactly the same as setting the @code{CIGNORE}

bit in the @code{c_cflag} member of the structure @var{termios-p} points

to.  @xref{Control Modes}, for a description of @code{CIGNORE}.

@end vtable

If this function is called from a background process on its controlling

terminal, normally all processes in the process group are sent a

@code{SIGTTOU} signal, in the same way as if the process were trying to

write to the terminal.  The exception is if the calling process itself

is ignoring or blocking @code{SIGTTOU} signals, in which case the

operation is performed and no signal is sent.  @xref{Job Control}.

If successful, @code{tcsetattr} returns @math{0}.  A return value of

@math{-1} indicates an error.  The following @code{errno} error

conditions are defined for this function:

@table @code

@item EBADF

The @var{filedes} argument is not a valid file descriptor.

@item ENOTTY

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

@item EINVAL

Either the value of the @code{when} argument is not valid, or there is

something wrong with the data in the @var{termios-p} argument.

@end table

@end deftypefun

Although @code{tcgetattr} and @code{tcsetattr} specify the terminal

device with a file descriptor, the attributes are those of the terminal

device itself and not of the file descriptor.  This means that the

effects of changing terminal attributes are persistent; if another

process opens the terminal file later on, it will see the changed

attributes even though it doesn't have anything to do with the open file

descriptor you originally specified in changing the attributes.

Similarly, if a single process has multiple or duplicated file

descriptors for the same terminal device, changing the terminal

attributes affects input and output to all of these file

descriptors.  This means, for example, that you can't open one file

descriptor or stream to read from a terminal in the normal

line-buffered, echoed mode; and simultaneously have another file

descriptor for the same terminal that you use to read from it in

single-character, non-echoed mode.  Instead, you have to explicitly

switch the terminal back and forth between the two modes.

@node Setting Modes

@subsection Setting Terminal Modes Properly

When you set terminal modes, you should call @code{tcgetattr} first to

get the current modes of the particular terminal device, modify only

those modes that you are really interested in, and store the result with

@code{tcsetattr}.

It's a bad idea to simply initialize a @code{struct termios} structure

to a chosen set of attributes and pass it directly to @code{tcsetattr}.

Your program may be run years from now, on systems that support members

not documented in this manual.  The way to avoid setting these members

to unreasonable values is to avoid changing them.

What's more, different terminal devices may require different mode

settings in order to function properly.  So you should avoid blindly

copying attributes from one terminal device to another.

When a member contains a collection of independent flags, as the

@code{c_iflag}, @code{c_oflag} and @code{c_cflag} members do, even

setting the entire member is a bad idea, because particular operating

systems have their own flags.  Instead, you should start with the

current value of the member and alter only the flags whose values matter

in your program, leaving any other flags unchanged.

Here is an example of how to set one flag (@code{ISTRIP}) in the

@code{struct termios} structure while properly preserving all the other

data in the structure:

@smallexample

@group

int

set_istrip (int desc, int value)

@{

  struct termios settings;

  int result;

@end group

@group

  result = tcgetattr (desc, &settings);

  if (result < 0)

    @{

      perror ("error in tcgetattr");

      return 0;

    @}

@end group

@group

  settings.c_iflag &= ~ISTRIP;

  if (value)

    settings.c_iflag |= ISTRIP;

@end group

@group

  result = tcsetattr (desc, TCSANOW, &settings);

  if (result < 0)

    @{

      perror ("error in tcsetattr");

      return 0;

   @}

  return 1;

@}

@end group

@end smallexample

@node Input Modes

@subsection Input Modes

This section describes the terminal attribute flags that control

fairly low-level aspects of input processing: handling of parity errors,

break signals, flow control, and @key{RET} and @key{LFD} characters.

All of these flags are bits in the @code{c_iflag} member of the

@code{struct termios} structure.  The member is an integer, and you

change flags using the operators @code{&}, @code{|} and @code{^}.  Don't

try to specify the entire value for @code{c_iflag}---instead, change

only specific flags and leave the rest untouched (@pxref{Setting

Modes}).

@deftypevr Macro tcflag_t INPCK

@standards{POSIX.1, termios.h}

@cindex parity checking

If this bit is set, input parity checking is enabled.  If it is not set,

no checking at all is done for parity errors on input; the

characters are simply passed through to the application.

Parity checking on input processing is independent of whether parity

detection and generation on the underlying terminal hardware is enabled;

see @ref{Control Modes}.  For example, you could clear the @code{INPCK}

input mode flag and set the @code{PARENB} control mode flag to ignore

parity errors on input, but still generate parity on output.

If this bit is set, what happens when a parity error is detected depends

on whether the @code{IGNPAR} or @code{PARMRK} bits are set.  If neither

of these bits are set, a byte with a parity error is passed to the

application as a @code{'\0'} character.

@end deftypevr

@deftypevr Macro tcflag_t IGNPAR

@standards{POSIX.1, termios.h}

If this bit is set, any byte with a framing or parity error is ignored.

This is only useful if @code{INPCK} is also set.

@end deftypevr

@deftypevr Macro tcflag_t PARMRK

@standards{POSIX.1, termios.h}

If this bit is set, input bytes with parity or framing errors are marked

when passed to the program.  This bit is meaningful only when

@code{INPCK} is set and @code{IGNPAR} is not set.

The way erroneous bytes are marked is with two preceding bytes,

@code{377} and @code{0}.  Thus, the program actually reads three bytes

for one erroneous byte received from the terminal.

If a valid byte has the value @code{0377}, and @code{ISTRIP} (see below)

is not set, the program might confuse it with the prefix that marks a

parity error.  So a valid byte @code{0377} is passed to the program as

two bytes, @code{0377} @code{0377}, in this case.

@end deftypevr

@deftypevr Macro tcflag_t ISTRIP

@standards{POSIX.1, termios.h}

If this bit is set, valid input bytes are stripped to seven bits;

otherwise, all eight bits are available for programs to read.

@end deftypevr

@deftypevr Macro tcflag_t IGNBRK

@standards{POSIX.1, termios.h}

If this bit is set, break conditions are ignored.

@cindex break condition, detecting

A @dfn{break condition} is defined in the context of asynchronous

serial data transmission as a series of zero-value bits longer than a

single byte.

@end deftypevr

@deftypevr Macro tcflag_t BRKINT

@standards{POSIX.1, termios.h}

If this bit is set and @code{IGNBRK} is not set, a break condition

clears the terminal input and output queues and raises a @code{SIGINT}

signal for the foreground process group associated with the terminal.

If neither @code{BRKINT} nor @code{IGNBRK} are set, a break condition is

passed to the application as a single @code{'\0'} character if

@code{PARMRK} is not set, or otherwise as a three-character sequence

@code{'\377'}, @code{'\0'}, @code{'\0'}.

@end deftypevr

@deftypevr Macro tcflag_t IGNCR

@standards{POSIX.1, termios.h}

If this bit is set, carriage return characters (@code{'\r'}) are

discarded on input.  Discarding carriage return may be useful on

terminals that send both carriage return and linefeed when you type the

@key{RET} key.

@end deftypevr

@deftypevr Macro tcflag_t ICRNL

@standards{POSIX.1, termios.h}

If this bit is set and @code{IGNCR} is not set, carriage return characters

(@code{'\r'}) received as input are passed to the application as newline

characters (@code{'\n'}).

@end deftypevr

@deftypevr Macro tcflag_t INLCR

@standards{POSIX.1, termios.h}

If this bit is set, newline characters (@code{'\n'}) received as input

are passed to the application as carriage return characters (@code{'\r'}).

@end deftypevr

@deftypevr Macro tcflag_t IXOFF

@standards{POSIX.1, termios.h}

If this bit is set, start/stop control on input is enabled.  In other

words, the computer sends STOP and START characters as necessary to

prevent input from coming in faster than programs are reading it.  The

idea is that the actual terminal hardware that is generating the input

data responds to a STOP character by suspending transmission, and to a

START character by resuming transmission.  @xref{Start/Stop Characters}.

@end deftypevr

@deftypevr Macro tcflag_t IXON

@standards{POSIX.1, termios.h}

If this bit is set, start/stop control on output is enabled.  In other

words, if the computer receives a STOP character, it suspends output

until a START character is received.  In this case, the STOP and START

characters are never passed to the application program.  If this bit is

not set, then START and STOP can be read as ordinary characters.

@xref{Start/Stop Characters}.

@c !!! mention this interferes with using C-s and C-q for programs like emacs

@end deftypevr

@deftypevr Macro tcflag_t IXANY

@standards{BSD, termios.h}

If this bit is set, any input character restarts output when output has

been suspended with the STOP character.  Otherwise, only the START

character restarts output.

This is a BSD extension; it exists only on BSD systems and

@gnulinuxhurdsystems{}.

@end deftypevr

@deftypevr Macro tcflag_t IMAXBEL

@standards{BSD, termios.h}

If this bit is set, then filling up the terminal input buffer sends a

BEL character (code @code{007}) to the terminal to ring the bell.

This is a BSD extension.

@end deftypevr

@node Output Modes

@subsection Output Modes

This section describes the terminal flags and fields that control how

output characters are translated and padded for display.  All of these

are contained in the @code{c_oflag} member of the @w{@code{struct termios}}

structure.

The @code{c_oflag} member itself is an integer, and you change the flags

and fields using the operators @code{&}, @code{|}, and @code{^}.  Don't

try to specify the entire value for @code{c_oflag}---instead, change

only specific flags and leave the rest untouched (@pxref{Setting

Modes}).

@deftypevr Macro tcflag_t OPOST

@standards{POSIX.1, termios.h}

If this bit is set, output data is processed in some unspecified way so

that it is displayed appropriately on the terminal device.  This

typically includes mapping newline characters (@code{'\n'}) onto

carriage return and linefeed pairs.

If this bit isn't set, the characters are transmitted as-is.

@end deftypevr

The following three bits are effective only if @code{OPOST} is set.

@deftypevr Macro tcflag_t ONLCR

@standards{POSIX.1, termios.h}

If this bit is set, convert the newline character on output into a pair

of characters, carriage return followed by linefeed.

@end deftypevr

@deftypevr Macro tcflag_t OXTABS

@standards{BSD, termios.h (optional)}

If this bit is set, convert tab characters on output into the appropriate

number of spaces to emulate a tab stop every eight columns.  This bit

exists only on BSD systems and @gnuhurdsystems{}; on

@gnulinuxsystems{} it is available as @code{XTABS}.

@end deftypevr

@deftypevr Macro tcflag_t ONOEOT

@standards{BSD, termios.h (optional)}

If this bit is set, discard @kbd{C-d} characters (code @code{004}) on

output.  These characters cause many dial-up terminals to disconnect.

This bit exists only on BSD systems and @gnuhurdsystems{}.

@end deftypevr

@node Control Modes

@subsection Control Modes

This section describes the terminal flags and fields that control

parameters usually associated with asynchronous serial data

transmission.  These flags may not make sense for other kinds of

terminal ports (such as a network connection pseudo-terminal).  All of

these are contained in the @code{c_cflag} member of the @code{struct

termios} structure.

The @code{c_cflag} member itself is an integer, and you change the flags

and fields using the operators @code{&}, @code{|}, and @code{^}.  Don't

try to specify the entire value for @code{c_cflag}---instead, change

only specific flags and leave the rest untouched (@pxref{Setting

Modes}).

@deftypevr Macro tcflag_t CLOCAL

@standards{POSIX.1, termios.h}

If this bit is set, it indicates that the terminal is connected

``locally'' and that the modem status lines (such as carrier detect)

should be ignored.

@cindex modem status lines

@cindex carrier detect

On many systems if this bit is not set and you call @code{open} without

the @code{O_NONBLOCK} flag set, @code{open} blocks until a modem

connection is established.

If this bit is not set and a modem disconnect is detected, a

@code{SIGHUP} signal is sent to the controlling process group for the

terminal (if it has one).  Normally, this causes the process to exit;

see @ref{Signal Handling}.  Reading from the terminal after a disconnect

causes an end-of-file condition, and writing causes an @code{EIO} error

to be returned.  The terminal device must be closed and reopened to

clear the condition.

@cindex modem disconnect

@end deftypevr

@deftypevr Macro tcflag_t HUPCL

@standards{POSIX.1, termios.h}

If this bit is set, a modem disconnect is generated when all processes

that have the terminal device open have either closed the file or exited.

@end deftypevr

@deftypevr Macro tcflag_t CREAD

@standards{POSIX.1, termios.h}

If this bit is set, input can be read from the terminal.  Otherwise,

input is discarded when it arrives.

@end deftypevr

@deftypevr Macro tcflag_t CSTOPB

@standards{POSIX.1, termios.h}

If this bit is set, two stop bits are used.  Otherwise, only one stop bit

is used.

@end deftypevr

@deftypevr Macro tcflag_t PARENB

@standards{POSIX.1, termios.h}

If this bit is set, generation and detection of a parity bit are enabled.

@xref{Input Modes}, for information on how input parity errors are handled.

If this bit is not set, no parity bit is added to output characters, and

input characters are not checked for correct parity.

@end deftypevr

@deftypevr Macro tcflag_t PARODD

@standards{POSIX.1, termios.h}

This bit is only useful if @code{PARENB} is set.  If @code{PARODD} is set,

odd parity is used, otherwise even parity is used.

@end deftypevr

The control mode flags also includes a field for the number of bits per

character.  You can use the @code{CSIZE} macro as a mask to extract the

value, like this: @code{settings.c_cflag & CSIZE}.

@deftypevr Macro tcflag_t CSIZE

@standards{POSIX.1, termios.h}

This is a mask for the number of bits per character.

@end deftypevr

@deftypevr Macro tcflag_t CS5

@standards{POSIX.1, termios.h}

This specifies five bits per byte.

@end deftypevr

@deftypevr Macro tcflag_t CS6

@standards{POSIX.1, termios.h}

This specifies six bits per byte.

@end deftypevr

@deftypevr Macro tcflag_t CS7

@standards{POSIX.1, termios.h}

This specifies seven bits per byte.

@end deftypevr

@deftypevr Macro tcflag_t CS8

@standards{POSIX.1, termios.h}

This specifies eight bits per byte.

@end deftypevr

The following four bits are BSD extensions; these exist only on BSD

systems and @gnuhurdsystems{}.

@deftypevr Macro tcflag_t CCTS_OFLOW

@standards{BSD, termios.h}

If this bit is set, enable flow control of output based on the CTS wire

(RS232 protocol).

@end deftypevr

@deftypevr Macro tcflag_t CRTS_IFLOW

@standards{BSD, termios.h}

If this bit is set, enable flow control of input based on the RTS wire

(RS232 protocol).

@end deftypevr

@deftypevr Macro tcflag_t MDMBUF

@standards{BSD, termios.h}

If this bit is set, enable carrier-based flow control of output.

@end deftypevr

@deftypevr Macro tcflag_t CIGNORE

@standards{BSD, termios.h}

If this bit is set, it says to ignore the control modes and line speed

values entirely.  This is only meaningful in a call to @code{tcsetattr}.

The @code{c_cflag} member and the line speed values returned by

@code{cfgetispeed} and @code{cfgetospeed} will be unaffected by the

call.  @code{CIGNORE} is useful if you want to set all the software

modes in the other members, but leave the hardware details in

@code{c_cflag} unchanged.  (This is how the @code{TCSASOFT} flag to

@code{tcsettattr} works.)

This bit is never set in the structure filled in by @code{tcgetattr}.

@end deftypevr

@node Local Modes

@subsection Local Modes

This section describes the flags for the @code{c_lflag} member of the

@code{struct termios} structure.  These flags generally control

higher-level aspects of input processing than the input modes flags

described in @ref{Input Modes}, such as echoing, signals, and the choice

of canonical or noncanonical input.

The @code{c_lflag} member itself is an integer, and you change the flags

and fields using the operators @code{&}, @code{|}, and @code{^}.  Don't

try to specify the entire value for @code{c_lflag}---instead, change

only specific flags and leave the rest untouched (@pxref{Setting

Modes}).

@deftypevr Macro tcflag_t ICANON

@standards{POSIX.1, termios.h}

This bit, if set, enables canonical input processing mode.  Otherwise,

input is processed in noncanonical mode.  @xref{Canonical or Not}.

@end deftypevr

@deftypevr Macro tcflag_t ECHO

@standards{POSIX.1, termios.h}

If this bit is set, echoing of input characters back to the terminal

is enabled.

@cindex echo of terminal input

@end deftypevr

@deftypevr Macro tcflag_t ECHOE

@standards{POSIX.1, termios.h}

If this bit is set, echoing indicates erasure of input with the ERASE

character by erasing the last character in the current line from the

screen.  Otherwise, the character erased is re-echoed to show what has

happened (suitable for a printing terminal).

This bit only controls the display behavior; the @code{ICANON} bit by

itself controls actual recognition of the ERASE character and erasure of

input, without which @code{ECHOE} is simply irrelevant.

@end deftypevr

@deftypevr Macro tcflag_t ECHOPRT

@standards{BSD, termios.h}

This bit, like @code{ECHOE}, enables display of the ERASE character in

a way that is geared to a hardcopy terminal.  When you type the ERASE

character, a @samp{\} character is printed followed by the first

character erased.  Typing the ERASE character again just prints the next

character erased.  Then, the next time you type a normal character, a

@samp{/} character is printed before the character echoes.

This is a BSD extension, and exists only in BSD systems and

@gnulinuxhurdsystems{}.

@end deftypevr

@deftypevr Macro tcflag_t ECHOK

@standards{POSIX.1, termios.h}

This bit enables special display of the KILL character by moving to a

new line after echoing the KILL character normally.  The behavior of

@code{ECHOKE} (below) is nicer to look at.

If this bit is not set, the KILL character echoes just as it would if it

were not the KILL character.  Then it is up to the user to remember that

the KILL character has erased the preceding input; there is no

indication of this on the screen.

This bit only controls the display behavior; the @code{ICANON} bit by

itself controls actual recognition of the KILL character and erasure of

input, without which @code{ECHOK} is simply irrelevant.

@end deftypevr

@deftypevr Macro tcflag_t ECHOKE

@standards{BSD, termios.h}

This bit is similar to @code{ECHOK}.  It enables special display of the

KILL character by erasing on the screen the entire line that has been

killed.  This is a BSD extension, and exists only in BSD systems and

@gnulinuxhurdsystems{}.

@end deftypevr

@deftypevr Macro tcflag_t ECHONL

@standards{POSIX.1, termios.h}

If this bit is set and the @code{ICANON} bit is also set, then the

newline (@code{'\n'}) character is echoed even if the @code{ECHO} bit

is not set.

@end deftypevr

@deftypevr Macro tcflag_t ECHOCTL

@standards{BSD, termios.h}

If this bit is set and the @code{ECHO} bit is also set, echo control

characters with @samp{^} followed by the corresponding text character.

Thus, control-A echoes as @samp{^A}.  This is usually the preferred mode

for interactive input, because echoing a control character back to the

terminal could have some undesired effect on the terminal.

This is a BSD extension, and exists only in BSD systems and

@gnulinuxhurdsystems{}.

@end deftypevr

@deftypevr Macro tcflag_t ISIG

@standards{POSIX.1, termios.h}