1: @node Low-Level Terminal Interface, Syslog, Sockets, Top
    2: @c %MENU% How to change the characteristics of a terminal device
    3: @chapter Low-Level Terminal Interface
    4: 
    5: This chapter describes functions that are specific to terminal devices.
    6: You can use these functions to do things like turn off input echoing;
    7: set serial line characteristics such as line speed and flow control; and
    8: change which characters are used for end-of-file, command-line editing,
    9: sending signals, and similar control functions.
   10: 
   11: Most of the functions in this chapter operate on file descriptors.
   12: @xref{Low-Level I/O}, for more information about what a file
   13: descriptor is and how to open a file descriptor for a terminal device.
   14: 
   15: @menu
   16: * Is It a Terminal::            How to determine if a file is a terminal
   17:                                  device, and what its name is.
   18: * I/O Queues::                  About flow control and typeahead.
   19: * Canonical or Not::            Two basic styles of input processing.
   20: * Terminal Modes::              How to examine and modify flags controlling
   21:                                  details of terminal I/O: echoing,
   22:                                  signals, editing.  Posix.
   23: * BSD Terminal Modes::          BSD compatible terminal mode setting
   24: * Line Control::                Sending break sequences, clearing
   25:                                  terminal buffers @dots{}
   26: * Noncanon Example::            How to read single characters without echo.
   27: * Pseudo-Terminals::            How to open a pseudo-terminal.
   28: @end menu
   29: 
   30: @node Is It a Terminal
   31: @section Identifying Terminals
   32: @cindex terminal identification
   33: @cindex identifying terminals
   34: 
   35: The functions described in this chapter only work on files that
   36: correspond to terminal devices.  You can find out whether a file
   37: descriptor is associated with a terminal by using the @code{isatty}
   38: function.
   39: 
   40: @pindex unistd.h
   41: Prototypes for the functions in this section are declared in the header
   42: file @file{unistd.h}.
   43: 
   44: @comment unistd.h
   45: @comment POSIX.1
   46: @deftypefun int isatty (int @var{filedes})
   47: This function returns @code{1} if @var{filedes} is a file descriptor
   48: associated with an open terminal device, and @math{0} otherwise.
   49: @end deftypefun
   50: 
   51: If a file descriptor is associated with a terminal, you can get its
   52: associated file name using the @code{ttyname} function.  See also the
   53: @code{ctermid} function, described in @ref{Identifying the Terminal}.
   54: 
   55: @comment unistd.h
   56: @comment POSIX.1
   57: @deftypefun {char *} ttyname (int @var{filedes})
   58: If the file descriptor @var{filedes} is associated with a terminal
   59: device, the @code{ttyname} function returns a pointer to a
   60: statically-allocated, null-terminated string containing the file name of
   61: the terminal file.  The value is a null pointer if the file descriptor
   62: isn't associated with a terminal, or the file name cannot be determined.
   63: @end deftypefun
   64: 
   65: @comment unistd.h
   66: @comment POSIX.1
   67: @deftypefun int ttyname_r (int @var{filedes}, char *@var{buf}, size_t @var{len})
   68: The @code{ttyname_r} function is similar to the @code{ttyname} function
   69: except that it places its result into the user-specified buffer starting
   70: at @var{buf} with length @var{len}.
   71: 
   72: The normal return value from @code{ttyname_r} is @math{0}.  Otherwise an
   73: error number is returned to indicate the error.  The following
   74: @code{errno} error conditions are defined for this function:
   75: 
   76: @table @code
   77: @item EBADF
   78: The @var{filedes} argument is not a valid file descriptor.
   79: 
   80: @item ENOTTY
   81: The @var{filedes} is not associated with a terminal.
   82: 
   83: @item ERANGE
   84: The buffer length @var{len} is too small to store the string to be
   85: returned.
   86: @end table
   87: @end deftypefun
   88: 
   89: @node I/O Queues
   90: @section I/O Queues
   91: 
   92: Many of the remaining functions in this section refer to the input and
   93: output queues of a terminal device.  These queues implement a form of
   94: buffering @emph{within the kernel} independent of the buffering
   95: implemented by I/O streams (@pxref{I/O on Streams}).
   96: 
   97: @cindex terminal input queue
   98: @cindex typeahead buffer
   99: The @dfn{terminal input queue} is also sometimes referred to as its
  100: @dfn{typeahead buffer}.  It holds the characters that have been received
  101: from the terminal but not yet read by any process.
  102: 
  103: The size of the input queue is described by the @code{MAX_INPUT} and
  104: @w{@code{_POSIX_MAX_INPUT}} parameters; see @ref{Limits for Files}.  You
  105: are guaranteed a queue size of at least @code{MAX_INPUT}, but the queue
  106: might be larger, and might even dynamically change size.  If input flow
  107: control is enabled by setting the @code{IXOFF} input mode bit
  108: (@pxref{Input Modes}), the terminal driver transmits STOP and START
  109: characters to the terminal when necessary to prevent the queue from
  110: overflowing.  Otherwise, input may be lost if it comes in too fast from
  111: the terminal.  In canonical mode, all input stays in the queue until a
  112: newline character is received, so the terminal input queue can fill up
  113: when you type a very long line.  @xref{Canonical or Not}.
  114: 
  115: @cindex terminal output queue
  116: The @dfn{terminal output queue} is like the input queue, but for output;
  117: it contains characters that have been written by processes, but not yet
  118: transmitted to the terminal.  If output flow control is enabled by
  119: setting the @code{IXON} input mode bit (@pxref{Input Modes}), the
  120: terminal driver obeys START and STOP characters sent by the terminal to
  121: stop and restart transmission of output.
  122: 
  123: @dfn{Clearing} the terminal input queue means discarding any characters
  124: that have been received but not yet read.  Similarly, clearing the
  125: terminal output queue means discarding any characters that have been
  126: written but not yet transmitted.
  127: 
  128: @node Canonical or Not
  129: @section Two Styles of Input: Canonical or Not
  130: 
  131: POSIX systems support two basic modes of input: canonical and
  132: noncanonical.
  133: 
  134: @cindex canonical input processing
  135: In @dfn{canonical input processing} mode, terminal input is processed in
  136: lines terminated by newline (@code{'\n'}), EOF, or EOL characters.  No
  137: input can be read until an entire line has been typed by the user, and
  138: the @code{read} function (@pxref{I/O Primitives}) returns at most a
  139: single line of input, no matter how many bytes are requested.
  140: 
  141: In canonical input mode, the operating system provides input editing
  142: facilities: some characters are interpreted specially to perform editing
  143: operations within the current line of text, such as ERASE and KILL.
  144: @xref{Editing Characters}.
  145: 
  146: The constants @code{_POSIX_MAX_CANON} and @code{MAX_CANON} parameterize
  147: the maximum number of bytes which may appear in a single line of
  148: canonical input.  @xref{Limits for Files}.  You are guaranteed a maximum
  149: line length of at least @code{MAX_CANON} bytes, but the maximum might be
  150: larger, and might even dynamically change size.
  151: 
  152: @cindex noncanonical input processing
  153: In @dfn{noncanonical input processing} mode, characters are not grouped
  154: into lines, and ERASE and KILL processing is not performed.  The
  155: granularity with which bytes are read in noncanonical input mode is
  156: controlled by the MIN and TIME settings.  @xref{Noncanonical Input}.
  157: 
  158: Most programs use canonical input mode, because this gives the user a
  159: way to edit input line by line.  The usual reason to use noncanonical
  160: mode is when the program accepts single-character commands or provides
  161: its own editing facilities.
  162: 
  163: The choice of canonical or noncanonical input is controlled by the
  164: @code{ICANON} flag in the @code{c_lflag} member of @code{struct termios}.
  165: @xref{Local Modes}.
  166: 
  167: @node Terminal Modes
  168: @section Terminal Modes
  169: 
  170: @pindex termios.h
  171: This section describes the various terminal attributes that control how
  172: input and output are done.  The functions, data structures, and symbolic
  173: constants are all declared in the header file @file{termios.h}.
  174: 
  175: Don't confuse terminal attributes with file attributes.  A device special
  176: file which is associated with a terminal has file attributes as described
  177: in @ref{File Attributes}.  These are unrelated to the attributes of the
  178: terminal device itself, which are discussed in this section.
  179: 
  180: @menu
  181: * Mode Data Types::             The data type @code{struct termios} and
  182:                                  related types.
  183: * Mode Functions::              Functions to read and set the terminal
  184:                                  attributes.
  185: * Setting Modes::               The right way to set terminal attributes
  186:                                  reliably.
  187: * Input Modes::                 Flags controlling low-level input handling.
  188: * Output Modes::                Flags controlling low-level output handling.
  189: * Control Modes::               Flags controlling serial port behavior.
  190: * Local Modes::                 Flags controlling high-level input handling.
  191: * Line Speed::                  How to read and set the terminal line speed.
  192: * Special Characters::          Characters that have special effects,
  193:                                  and how to change them.
  194: * Noncanonical Input::          Controlling how long to wait for input.
  195: @end menu
  196: 
  197: @node Mode Data Types
  198: @subsection Terminal Mode Data Types
  199: @cindex terminal mode data types
  200: 
  201: The entire collection of attributes of a terminal is stored in a
  202: structure of type @code{struct termios}.  This structure is used
  203: with the functions @code{tcgetattr} and @code{tcsetattr} to read
  204: and set the attributes.
  205: 
  206: @comment termios.h
  207: @comment POSIX.1
  208: @deftp {Data Type} {struct termios}
  209: Structure that records all the I/O attributes of a terminal.  The
  210: structure includes at least the following members:
  211: 
  212: @table @code
  213: @item tcflag_t c_iflag
  214: A bit mask specifying flags for input modes; see @ref{Input Modes}.
  215: 
  216: @item tcflag_t c_oflag
  217: A bit mask specifying flags for output modes; see @ref{Output Modes}.
  218: 
  219: @item tcflag_t c_cflag
  220: A bit mask specifying flags for control modes; see @ref{Control Modes}.
  221: 
  222: @item tcflag_t c_lflag
  223: A bit mask specifying flags for local modes; see @ref{Local Modes}.
  224: 
  225: @item cc_t c_cc[NCCS]
  226: An array specifying which characters are associated with various
  227: control functions; see @ref{Special Characters}.
  228: @end table
  229: 
  230: The @code{struct termios} structure also contains members which
  231: encode input and output transmission speeds, but the representation is
  232: not specified.  @xref{Line Speed}, for how to examine and store the
  233: speed values.
  234: @end deftp
  235: 
  236: The following sections describe the details of the members of the
  237: @code{struct termios} structure.
  238: 
  239: @comment termios.h
  240: @comment POSIX.1
  241: @deftp {Data Type} tcflag_t
  242: This is an unsigned integer type used to represent the various
  243: bit masks for terminal flags.
  244: @end deftp
  245: 
  246: @comment termios.h
  247: @comment POSIX.1
  248: @deftp {Data Type} cc_t
  249: This is an unsigned integer type used to represent characters associated
  250: with various terminal control functions.
  251: @end deftp
  252: 
  253: @comment termios.h
  254: @comment POSIX.1
  255: @deftypevr Macro int NCCS
  256: The value of this macro is the number of elements in the @code{c_cc}
  257: array.
  258: @end deftypevr
  259: 
  260: @node Mode Functions
  261: @subsection Terminal Mode Functions
  262: @cindex terminal mode functions
  263: 
  264: @comment termios.h
  265: @comment POSIX.1
  266: @deftypefun int tcgetattr (int @var{filedes}, struct termios *@var{termios-p})
  267: This function is used to examine the attributes of the terminal
  268: device with file descriptor @var{filedes}.  The attributes are returned
  269: in the structure that @var{termios-p} points to.
  270: 
  271: If successful, @code{tcgetattr} returns @math{0}.  A return value of @math{-1}
  272: indicates an error.  The following @code{errno} error conditions are
  273: defined for this function:
  274: 
  275: @table @code
  276: @item EBADF
  277: The @var{filedes} argument is not a valid file descriptor.
  278: 
  279: @item ENOTTY
  280: The @var{filedes} is not associated with a terminal.
  281: @end table
  282: @end deftypefun
  283: 
  284: @comment termios.h
  285: @comment POSIX.1
  286: @deftypefun int tcsetattr (int @var{filedes}, int @var{when}, const struct termios *@var{termios-p})
  287: This function sets the attributes of the terminal device with file
  288: descriptor @var{filedes}.  The new attributes are taken from the
  289: structure that @var{termios-p} points to.
  290: 
  291: The @var{when} argument specifies how to deal with input and output
  292: already queued.  It can be one of the following values:
  293: 
  294: @table @code
  295: @comment termios.h
  296: @comment POSIX.1
  297: @item TCSANOW
  298: @vindex TCSANOW
  299: Make the change immediately.
  300: 
  301: @comment termios.h
  302: @comment POSIX.1
  303: @item TCSADRAIN
  304: @vindex TCSADRAIN
  305: Make the change after waiting until all queued output has been written.
  306: You should usually use this option when changing parameters that affect
  307: output.
  308: 
  309: @comment termios.h
  310: @comment POSIX.1
  311: @item TCSAFLUSH
  312: @vindex TCSAFLUSH
  313: This is like @code{TCSADRAIN}, but also discards any queued input.
  314: 
  315: @comment termios.h
  316: @comment BSD
  317: @item TCSASOFT
  318: @vindex TCSASOFT
  319: This is a flag bit that you can add to any of the above alternatives.
  320: Its meaning is to inhibit alteration of the state of the terminal
  321: hardware.  It is a BSD extension; it is only supported on BSD systems
  322: and the GNU system.
  323: 
  324: Using @code{TCSASOFT} is exactly the same as setting the @code{CIGNORE}
  325: bit in the @code{c_cflag} member of the structure @var{termios-p} points
  326: to.  @xref{Control Modes}, for a description of @code{CIGNORE}.
  327: @end table
  328: 
  329: If this function is called from a background process on its controlling
  330: terminal, normally all processes in the process group are sent a
  331: @code{SIGTTOU} signal, in the same way as if the process were trying to
  332: write to the terminal.  The exception is if the calling process itself
  333: is ignoring or blocking @code{SIGTTOU} signals, in which case the
  334: operation is performed and no signal is sent.  @xref{Job Control}.
  335: 
  336: If successful, @code{tcsetattr} returns @math{0}.  A return value of
  337: @math{-1} indicates an error.  The following @code{errno} error
  338: conditions are defined for this function:
  339: 
  340: @table @code
  341: @item EBADF
  342: The @var{filedes} argument is not a valid file descriptor.
  343: 
  344: @item ENOTTY
  345: The @var{filedes} is not associated with a terminal.
  346: 
  347: @item EINVAL
  348: Either the value of the @code{when} argument is not valid, or there is
  349: something wrong with the data in the @var{termios-p} argument.
  350: @end table
  351: @end deftypefun
  352: 
  353: Although @code{tcgetattr} and @code{tcsetattr} specify the terminal
  354: device with a file descriptor, the attributes are those of the terminal
  355: device itself and not of the file descriptor.  This means that the
  356: effects of changing terminal attributes are persistent; if another
  357: process opens the terminal file later on, it will see the changed
  358: attributes even though it doesn't have anything to do with the open file
  359: descriptor you originally specified in changing the attributes.
  360: 
  361: Similarly, if a single process has multiple or duplicated file
  362: descriptors for the same terminal device, changing the terminal
  363: attributes affects input and output to all of these file
  364: descriptors.  This means, for example, that you can't open one file
  365: descriptor or stream to read from a terminal in the normal
  366: line-buffered, echoed mode; and simultaneously have another file
  367: descriptor for the same terminal that you use to read from it in
  368: single-character, non-echoed mode.  Instead, you have to explicitly
  369: switch the terminal back and forth between the two modes.
  370: 
  371: @node Setting Modes
  372: @subsection Setting Terminal Modes Properly
  373: 
  374: When you set terminal modes, you should call @code{tcgetattr} first to
  375: get the current modes of the particular terminal device, modify only
  376: those modes that you are really interested in, and store the result with
  377: @code{tcsetattr}.
  378: 
  379: It's a bad idea to simply initialize a @code{struct termios} structure
  380: to a chosen set of attributes and pass it directly to @code{tcsetattr}.
  381: Your program may be run years from now, on systems that support members
  382: not documented in this manual.  The way to avoid setting these members
  383: to unreasonable values is to avoid changing them.
  384: 
  385: What's more, different terminal devices may require different mode
  386: settings in order to function properly.  So you should avoid blindly
  387: copying attributes from one terminal device to another.
  388: 
  389: When a member contains a collection of independent flags, as the
  390: @code{c_iflag}, @code{c_oflag} and @code{c_cflag} members do, even
  391: setting the entire member is a bad idea, because particular operating
  392: systems have their own flags.  Instead, you should start with the
  393: current value of the member and alter only the flags whose values matter
  394: in your program, leaving any other flags unchanged.
  395: 
  396: Here is an example of how to set one flag (@code{ISTRIP}) in the
  397: @code{struct termios} structure while properly preserving all the other
  398: data in the structure:
  399: 
  400: @smallexample
  401: @group
  402: int
  403: set_istrip (int desc, int value)
  404: @{
  405:   struct termios settings;
  406:   int result;
  407: @end group
  408: 
  409: @group
  410:   result = tcgetattr (desc, &settings);
  411:   if (result < 0)
  412:     @{
  413:       perror ("error in tcgetattr");
  414:       return 0;
  415:     @}
  416: @end group
  417: @group
  418:   settings.c_iflag &= ~ISTRIP;
  419:   if (value)
  420:     settings.c_iflag |= ISTRIP;
  421: @end group
  422: @group
  423:   result = tcsetattr (desc, TCSANOW, &settings);
  424:   if (result < 0)
  425:     @{
  426:       perror ("error in tcsetattr");
  427:       return 0;
  428:    @}
  429:   return 1;
  430: @}
  431: @end group
  432: @end smallexample
  433: 
  434: @node Input Modes
  435: @subsection Input Modes
  436: 
  437: This section describes the terminal attribute flags that control
  438: fairly low-level aspects of input processing: handling of parity errors,
  439: break signals, flow control, and @key{RET} and @key{LFD} characters.
  440: 
  441: All of these flags are bits in the @code{c_iflag} member of the
  442: @code{struct termios} structure.  The member is an integer, and you
  443: change flags using the operators @code{&}, @code{|} and @code{^}.  Don't
  444: try to specify the entire value for @code{c_iflag}---instead, change
  445: only specific flags and leave the rest untouched (@pxref{Setting
  446: Modes}).
  447: 
  448: @comment termios.h
  449: @comment POSIX.1
  450: @deftypevr Macro tcflag_t INPCK
  451: @cindex parity checking
  452: If this bit is set, input parity checking is enabled.  If it is not set,
  453: no checking at all is done for parity errors on input; the
  454: characters are simply passed through to the application.
  455: 
  456: Parity checking on input processing is independent of whether parity
  457: detection and generation on the underlying terminal hardware is enabled;
  458: see @ref{Control Modes}.  For example, you could clear the @code{INPCK}
  459: input mode flag and set the @code{PARENB} control mode flag to ignore
  460: parity errors on input, but still generate parity on output.
  461: 
  462: If this bit is set, what happens when a parity error is detected depends
  463: on whether the @code{IGNPAR} or @code{PARMRK} bits are set.  If neither
  464: of these bits are set, a byte with a parity error is passed to the
  465: application as a @code{'\0'} character.
  466: @end deftypevr
  467: 
  468: @comment termios.h
  469: @comment POSIX.1
  470: @deftypevr Macro tcflag_t IGNPAR
  471: If this bit is set, any byte with a framing or parity error is ignored.
  472: This is only useful if @code{INPCK} is also set.
  473: @end deftypevr
  474: 
  475: @comment termios.h
  476: @comment POSIX.1
  477: @deftypevr Macro tcflag_t PARMRK
  478: If this bit is set, input bytes with parity or framing errors are marked
  479: when passed to the program.  This bit is meaningful only when
  480: @code{INPCK} is set and @code{IGNPAR} is not set.
  481: 
  482: The way erroneous bytes are marked is with two preceding bytes,
  483: @code{377} and @code{0}.  Thus, the program actually reads three bytes
  484: for one erroneous byte received from the terminal.
  485: 
  486: If a valid byte has the value @code{0377}, and @code{ISTRIP} (see below)
  487: is not set, the program might confuse it with the prefix that marks a
  488: parity error.  So a valid byte @code{0377} is passed to the program as
  489: two bytes, @code{0377} @code{0377}, in this case.
  490: @end deftypevr
  491: 
  492: @comment termios.h
  493: @comment POSIX.1
  494: @deftypevr Macro tcflag_t ISTRIP
  495: If this bit is set, valid input bytes are stripped to seven bits;
  496: otherwise, all eight bits are available for programs to read.
  497: @end deftypevr
  498: 
  499: @comment termios.h
  500: @comment POSIX.1
  501: @deftypevr Macro tcflag_t IGNBRK
  502: If this bit is set, break conditions are ignored.
  503: 
  504: @cindex break condition, detecting
  505: A @dfn{break condition} is defined in the context of asynchronous
  506: serial data transmission as a series of zero-value bits longer than a
  507: single byte.
  508: @end deftypevr
  509: 
  510: @comment termios.h
  511: @comment POSIX.1
  512: @deftypevr Macro tcflag_t BRKINT
  513: If this bit is set and @code{IGNBRK} is not set, a break condition
  514: clears the terminal input and output queues and raises a @code{SIGINT}
  515: signal for the foreground process group associated with the terminal.
  516: 
  517: If neither @code{BRKINT} nor @code{IGNBRK} are set, a break condition is
  518: passed to the application as a single @code{'\0'} character if
  519: @code{PARMRK} is not set, or otherwise as a three-character sequence
  520: @code{'\377'}, @code{'\0'}, @code{'\0'}.
  521: @end deftypevr
  522: 
  523: @comment termios.h
  524: @comment POSIX.1
  525: @deftypevr Macro tcflag_t IGNCR
  526: If this bit is set, carriage return characters (@code{'\r'}) are
  527: discarded on input.  Discarding carriage return may be useful on
  528: terminals that send both carriage return and linefeed when you type the
  529: @key{RET} key.
  530: @end deftypevr
  531: 
  532: @comment termios.h
  533: @comment POSIX.1
  534: @deftypevr Macro tcflag_t ICRNL
  535: If this bit is set and @code{IGNCR} is not set, carriage return characters
  536: (@code{'\r'}) received as input are passed to the application as newline
  537: characters (@code{'\n'}).
  538: @end deftypevr
  539: 
  540: @comment termios.h
  541: @comment POSIX.1
  542: @deftypevr Macro tcflag_t INLCR
  543: If this bit is set, newline characters (@code{'\n'}) received as input
  544: are passed to the application as carriage return characters (@code{'\r'}).
  545: @end deftypevr
  546: 
  547: @comment termios.h
  548: @comment POSIX.1
  549: @deftypevr Macro tcflag_t IXOFF
  550: If this bit is set, start/stop control on input is enabled.  In other
  551: words, the computer sends STOP and START characters as necessary to
  552: prevent input from coming in faster than programs are reading it.  The
  553: idea is that the actual terminal hardware that is generating the input
  554: data responds to a STOP character by suspending transmission, and to a
  555: START character by resuming transmission.  @xref{Start/Stop Characters}.
  556: @end deftypevr
  557: 
  558: @comment termios.h
  559: @comment POSIX.1
  560: @deftypevr Macro tcflag_t IXON
  561: If this bit is set, start/stop control on output is enabled.  In other
  562: words, if the computer receives a STOP character, it suspends output
  563: until a START character is received.  In this case, the STOP and START
  564: characters are never passed to the application program.  If this bit is
  565: not set, then START and STOP can be read as ordinary characters.
  566: @xref{Start/Stop Characters}.
  567: @c !!! mention this interferes with using C-s and C-q for programs like emacs
  568: @end deftypevr
  569: 
  570: @comment termios.h
  571: @comment BSD
  572: @deftypevr Macro tcflag_t IXANY
  573: If this bit is set, any input character restarts output when output has
  574: been suspended with the STOP character.  Otherwise, only the START
  575: character restarts output.
  576: 
  577: This is a BSD extension; it exists only on BSD systems and the GNU system.
  578: @end deftypevr
  579: 
  580: @comment termios.h
  581: @comment BSD
  582: @deftypevr Macro tcflag_t IMAXBEL
  583: If this bit is set, then filling up the terminal input buffer sends a
  584: BEL character (code @code{007}) to the terminal to ring the bell.
  585: 
  586: This is a BSD extension.
  587: @end deftypevr
  588: 
  589: @node Output Modes
  590: @subsection Output Modes
  591: 
  592: This section describes the terminal flags and fields that control how
  593: output characters are translated and padded for display.  All of these
  594: are contained in the @code{c_oflag} member of the @w{@code{struct termios}}
  595: structure.
  596: 
  597: The @code{c_oflag} member itself is an integer, and you change the flags
  598: and fields using the operators @code{&}, @code{|}, and @code{^}.  Don't
  599: try to specify the entire value for @code{c_oflag}---instead, change
  600: only specific flags and leave the rest untouched (@pxref{Setting
  601: Modes}).
  602: 
  603: @comment termios.h
  604: @comment POSIX.1
  605: @deftypevr Macro tcflag_t OPOST
  606: If this bit is set, output data is processed in some unspecified way so
  607: that it is displayed appropriately on the terminal device.  This
  608: typically includes mapping newline characters (@code{'\n'}) onto
  609: carriage return and linefeed pairs.
  610: 
  611: If this bit isn't set, the characters are transmitted as-is.
  612: @end deftypevr
  613: 
  614: The following three bits are BSD features, and they exist only BSD
  615: systems and the GNU system.  They are effective only if @code{OPOST} is
  616: set.
  617: 
  618: @comment termios.h
  619: @comment BSD
  620: @deftypevr Macro tcflag_t ONLCR
  621: If this bit is set, convert the newline character on output into a pair
  622: of characters, carriage return followed by linefeed.
  623: @end deftypevr
  624: 
  625: @comment termios.h
  626: @comment BSD
  627: @deftypevr Macro tcflag_t OXTABS
  628: If this bit is set, convert tab characters on output into the appropriate
  629: number of spaces to emulate a tab stop every eight columns.
  630: @end deftypevr
  631: 
  632: @comment termios.h
  633: @comment BSD
  634: @deftypevr Macro tcflag_t ONOEOT
  635: If this bit is set, discard @kbd{C-d} characters (code @code{004}) on
  636: output.  These characters cause many dial-up terminals to disconnect.
  637: @end deftypevr
  638: 
  639: @node Control Modes
  640: @subsection Control Modes
  641: 
  642: This section describes the terminal flags and fields that control
  643: parameters usually associated with asynchronous serial data
  644: transmission.  These flags may not make sense for other kinds of
  645: terminal ports (such as a network connection pseudo-terminal).  All of
  646: these are contained in the @code{c_cflag} member of the @code{struct
  647: termios} structure.
  648: 
  649: The @code{c_cflag} member itself is an integer, and you change the flags
  650: and fields using the operators @code{&}, @code{|}, and @code{^}.  Don't
  651: try to specify the entire value for @code{c_cflag}---instead, change
  652: only specific flags and leave the rest untouched (@pxref{Setting
  653: Modes}).
  654: 
  655: @comment termios.h
  656: @comment POSIX.1
  657: @deftypevr Macro tcflag_t CLOCAL
  658: If this bit is set, it indicates that the terminal is connected
  659: ``locally'' and that the modem status lines (such as carrier detect)
  660: should be ignored.
  661: @cindex modem status lines
  662: @cindex carrier detect
  663: 
  664: On many systems if this bit is not set and you call @code{open} without
  665: the @code{O_NONBLOCK} flag set, @code{open} blocks until a modem
  666: connection is established.
  667: 
  668: If this bit is not set and a modem disconnect is detected, a
  669: @code{SIGHUP} signal is sent to the controlling process group for the
  670: terminal (if it has one).  Normally, this causes the process to exit;
  671: see @ref{Signal Handling}.  Reading from the terminal after a disconnect
  672: causes an end-of-file condition, and writing causes an @code{EIO} error
  673: to be returned.  The terminal device must be closed and reopened to
  674: clear the condition.
  675: @cindex modem disconnect
  676: @end deftypevr
  677: 
  678: @comment termios.h
  679: @comment POSIX.1
  680: @deftypevr Macro tcflag_t HUPCL
  681: If this bit is set, a modem disconnect is generated when all processes
  682: that have the terminal device open have either closed the file or exited.
  683: @end deftypevr
  684: 
  685: @comment termios.h
  686: @comment POSIX.1
  687: @deftypevr Macro tcflag_t CREAD
  688: If this bit is set, input can be read from the terminal.  Otherwise,
  689: input is discarded when it arrives.
  690: @end deftypevr
  691: 
  692: @comment termios.h
  693: @comment POSIX.1
  694: @deftypevr Macro tcflag_t CSTOPB
  695: If this bit is set, two stop bits are used.  Otherwise, only one stop bit
  696: is used.
  697: @end deftypevr
  698: 
  699: @comment termios.h
  700: @comment POSIX.1
  701: @deftypevr Macro tcflag_t PARENB
  702: If this bit is set, generation and detection of a parity bit are enabled.
  703: @xref{Input Modes}, for information on how input parity errors are handled.
  704: 
  705: If this bit is not set, no parity bit is added to output characters, and
  706: input characters are not checked for correct parity.
  707: @end deftypevr
  708: 
  709: @comment termios.h
  710: @comment POSIX.1
  711: @deftypevr Macro tcflag_t PARODD
  712: This bit is only useful if @code{PARENB} is set.  If @code{PARODD} is set,
  713: odd parity is used, otherwise even parity is used.
  714: @end deftypevr
  715: 
  716: The control mode flags also includes a field for the number of bits per
  717: character.  You can use the @code{CSIZE} macro as a mask to extract the
  718: value, like this: @code{settings.c_cflag & CSIZE}.
  719: 
  720: @comment termios.h
  721: @comment POSIX.1
  722: @deftypevr Macro tcflag_t CSIZE
  723: This is a mask for the number of bits per character.
  724: @end deftypevr
  725: 
  726: @comment termios.h
  727: @comment POSIX.1
  728: @deftypevr Macro tcflag_t CS5
  729: This specifies five bits per byte.
  730: @end deftypevr
  731: 
  732: @comment termios.h
  733: @comment POSIX.1
  734: @deftypevr Macro tcflag_t CS6
  735: This specifies six bits per byte.
  736: @end deftypevr
  737: 
  738: @comment termios.h
  739: @comment POSIX.1
  740: @deftypevr Macro tcflag_t CS7
  741: This specifies seven bits per byte.
  742: @end deftypevr
  743: 
  744: @comment termios.h
  745: @comment POSIX.1
  746: @deftypevr Macro tcflag_t CS8
  747: This specifies eight bits per byte.
  748: @end deftypevr
  749: 
  750: The following four bits are BSD extensions; this exist only on BSD
  751: systems and the GNU system.
  752: 
  753: @comment termios.h