This is Info file libc.info, produced by Makeinfo version 1.68 from the
input file libc.texinfo.

INFO-DIR-SECTION GNU libraries
START-INFO-DIR-ENTRY
* Libc: (libc).                 C library.
END-INFO-DIR-ENTRY

   This file documents the GNU C library.

   This is Edition 0.08 DRAFT, last updated 11 Jan 1999, of `The GNU C
Library Reference Manual', for Version 2.1 Beta.

   Copyright (C) 1993, '94, '95, '96, '97, '98, '99 Free Software
Foundation, Inc.

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided also
that the section entitled "GNU Library General Public License" is
included exactly as in the original, and provided that the entire
resulting derived work is distributed under the terms of a permission
notice identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that the text of the translation of the section
entitled "GNU Library General Public License" must be approved for
accuracy by the Foundation.


File: libc.info,  Node: Line Speed,  Next: Special Characters,  Prev: Local Modes,  Up: Terminal Modes

Line Speed
----------

   The terminal line speed tells the computer how fast to read and write
data on the terminal.

   If the terminal is connected to a real serial line, the terminal
speed you specify actually controls the line--if it doesn't match the
terminal's own idea of the speed, communication does not work.  Real
serial ports accept only certain standard speeds.  Also, particular
hardware may not support even all the standard speeds.  Specifying a
speed of zero hangs up a dialup connection and turns off modem control
signals.

   If the terminal is not a real serial line (for example, if it is a
network connection), then the line speed won't really affect data
transmission speed, but some programs will use it to determine the
amount of padding needed.  It's best to specify a line speed value that
matches the actual speed of the actual terminal, but you can safely
experiment with different values to vary the amount of padding.

   There are actually two line speeds for each terminal, one for input
and one for output.  You can set them independently, but most often
terminals use the same speed for both directions.

   The speed values are stored in the `struct termios' structure, but
don't try to access them in the `struct termios' structure directly.
Instead, you should use the following functions to read and store them:

 - Function: speed_t cfgetospeed (const struct termios *TERMIOS-P)
     This function returns the output line speed stored in the structure
     `*TERMIOS-P'.

 - Function: speed_t cfgetispeed (const struct termios *TERMIOS-P)
     This function returns the input line speed stored in the structure
     `*TERMIOS-P'.

 - Function: int cfsetospeed (struct termios *TERMIOS-P, speed_t SPEED)
     This function stores SPEED in `*TERMIOS-P' as the output speed.
     The normal return value is 0; a value of -1 indicates an error.
     If SPEED is not a speed, `cfsetospeed' returns -1.

 - Function: int cfsetispeed (struct termios *TERMIOS-P, speed_t SPEED)
     This function stores SPEED in `*TERMIOS-P' as the input speed.
     The normal return value is 0; a value of -1 indicates an error.
     If SPEED is not a speed, `cfsetospeed' returns -1.

 - Function: int cfsetspeed (struct termios *TERMIOS-P, speed_t SPEED)
     This function stores SPEED in `*TERMIOS-P' as both the input and
     output speeds.  The normal return value is 0; a value of -1
     indicates an error.  If SPEED is not a speed, `cfsetspeed' returns
     -1.  This function is an extension in 4.4 BSD.

 - Data Type: speed_t
     The `speed_t' type is an unsigned integer data type used to
     represent line speeds.

   The functions `cfsetospeed' and `cfsetispeed' report errors only for
speed values that the system simply cannot handle.  If you specify a
speed value that is basically acceptable, then those functions will
succeed.  But they do not check that a particular hardware device can
actually support the specified speeds--in fact, they don't know which
device you plan to set the speed for.  If you use `tcsetattr' to set
the speed of a particular device to a value that it cannot handle,
`tcsetattr' returns -1.

   *Portability note:* In the GNU library, the functions above accept
speeds measured in bits per second as input, and return speed values
measured in bits per second.  Other libraries require speeds to be
indicated by special codes.  For POSIX.1 portability, you must use one
of the following symbols to represent the speed; their precise numeric
values are system-dependent, but each name has a fixed meaning: `B110'
stands for 110 bps, `B300' for 300 bps, and so on.  There is no
portable way to represent any speed but these, but these are the only
speeds that typical serial lines can support.

     B0  B50  B75  B110  B134  B150  B200
     B300  B600  B1200  B1800  B2400  B4800
     B9600  B19200  B38400  B57600  B115200
     B230400  B460800

   BSD defines two additional speed symbols as aliases: `EXTA' is an
alias for `B19200' and `EXTB' is an alias for `B38400'.  These aliases
are obsolete.


File: libc.info,  Node: Special Characters,  Next: Noncanonical Input,  Prev: Line Speed,  Up: Terminal Modes

Special Characters
------------------

   In canonical input, the terminal driver recognizes a number of
special characters which perform various control functions.  These
include the ERASE character (usually <DEL>) for editing input, and
other editing characters.  The INTR character (normally `C-c') for
sending a `SIGINT' signal, and other signal-raising characters, may be
available in either canonical or noncanonical input mode.  All these
characters are described in this section.

   The particular characters used are specified in the `c_cc' member of
the `struct termios' structure.  This member is an array; each element
specifies the character for a particular role.  Each element has a
symbolic constant that stands for the index of that element--for
example, `VINTR' is the index of the element that specifies the INTR
character, so storing `'='' in `TERMIOS.c_cc[VINTR]' specifies `=' as
the INTR character.

   On some systems, you can disable a particular special character
function by specifying the value `_POSIX_VDISABLE' for that role.  This
value is unequal to any possible character code.  *Note Options for
Files::, for more information about how to tell whether the operating
system you are using supports `_POSIX_VDISABLE'.

* Menu:

* Editing Characters::          Special characters that terminate lines and
                                  delete text, and other editing functions.
* Signal Characters::           Special characters that send or raise signals
                                  to or for certain classes of processes.
* Start/Stop Characters::       Special characters that suspend or resume
                                  suspended output.
* Other Special::		Other special characters for BSD systems:
				  they can discard output, and print status.


File: libc.info,  Node: Editing Characters,  Next: Signal Characters,  Up: Special Characters

Characters for Input Editing
............................

   These special characters are active only in canonical input mode.
*Note Canonical or Not::.

 - Macro: int VEOF
     This is the subscript for the EOF character in the special control
     character array.  `TERMIOS.c_cc[VEOF]' holds the character itself.

     The EOF character is recognized only in canonical input mode.  It
     acts as a line terminator in the same way as a newline character,
     but if the EOF character is typed at the beginning of a line it
     causes `read' to return a byte count of zero, indicating
     end-of-file.  The EOF character itself is discarded.

     Usually, the EOF character is `C-d'.

 - Macro: int VEOL
     This is the subscript for the EOL character in the special control
     character array.  `TERMIOS.c_cc[VEOL]' holds the character itself.

     The EOL character is recognized only in canonical input mode.  It
     acts as a line terminator, just like a newline character.  The EOL
     character is not discarded; it is read as the last character in
     the input line.

     You don't need to use the EOL character to make <RET> end a line.
     Just set the ICRNL flag.  In fact, this is the default state of
     affairs.

 - Macro: int VEOL2
     This is the subscript for the EOL2 character in the special control
     character array.  `TERMIOS.c_cc[VEOL2]' holds the character itself.

     The EOL2 character works just like the EOL character (see above),
     but it can be a different character.  Thus, you can specify two
     characters to terminate an input line, by setting EOL to one of
     them and EOL2 to the other.

     The EOL2 character is a BSD extension; it exists only on BSD
     systems and the GNU system.

 - Macro: int VERASE
     This is the subscript for the ERASE character in the special
     control character array.  `TERMIOS.c_cc[VERASE]' holds the
     character itself.

     The ERASE character is recognized only in canonical input mode.
     When the user types the erase character, the previous character
     typed is discarded.  (If the terminal generates multibyte
     character sequences, this may cause more than one byte of input to
     be discarded.)  This cannot be used to erase past the beginning of
     the current line of text.  The ERASE character itself is discarded.

     Usually, the ERASE character is <DEL>.

 - Macro: int VWERASE
     This is the subscript for the WERASE character in the special
     control character array.  `TERMIOS.c_cc[VWERASE]' holds the
     character itself.

     The WERASE character is recognized only in canonical mode.  It
     erases an entire word of prior input, and any whitespace after it;
     whitespace characters before the word are not erased.

     The definition of a "word" depends on the setting of the
     `ALTWERASE' mode; *note Local Modes::..

     If the `ALTWERASE' mode is not set, a word is defined as a sequence
     of any characters except space or tab.

     If the `ALTWERASE' mode is set, a word is defined as a sequence of
     characters containing only letters, numbers, and underscores,
     optionally followed by one character that is not a letter, number,
     or underscore.

     The WERASE character is usually `C-w'.

     This is a BSD extension.

 - Macro: int VKILL
     This is the subscript for the KILL character in the special control
     character array.  `TERMIOS.c_cc[VKILL]' holds the character itself.

     The KILL character is recognized only in canonical input mode.
     When the user types the kill character, the entire contents of the
     current line of input are discarded.  The kill character itself is
     discarded too.

     The KILL character is usually `C-u'.

 - Macro: int VREPRINT
     This is the subscript for the REPRINT character in the special
     control character array.  `TERMIOS.c_cc[VREPRINT]' holds the
     character itself.

     The REPRINT character is recognized only in canonical mode.  It
     reprints the current input line.  If some asynchronous output has
     come while you are typing, this lets you see the line you are
     typing clearly again.

     The REPRINT character is usually `C-r'.

     This is a BSD extension.


File: libc.info,  Node: Signal Characters,  Next: Start/Stop Characters,  Prev: Editing Characters,  Up: Special Characters

Characters that Cause Signals
.............................

   These special characters may be active in either canonical or
noncanonical input mode, but only when the `ISIG' flag is set (*note
Local Modes::.).

 - Macro: int VINTR
     This is the subscript for the INTR character in the special control
     character array.  `TERMIOS.c_cc[VINTR]' holds the character itself.

     The INTR (interrupt) character raises a `SIGINT' signal for all
     processes in the foreground job associated with the terminal.  The
     INTR character itself is then discarded.  *Note Signal Handling::,
     for more information about signals.

     Typically, the INTR character is `C-c'.

 - Macro: int VQUIT
     This is the subscript for the QUIT character in the special control
     character array.  `TERMIOS.c_cc[VQUIT]' holds the character itself.

     The QUIT character raises a `SIGQUIT' signal for all processes in
     the foreground job associated with the terminal.  The QUIT
     character itself is then discarded.  *Note Signal Handling::, for
     more information about signals.

     Typically, the QUIT character is `C-\'.

 - Macro: int VSUSP
     This is the subscript for the SUSP character in the special control
     character array.  `TERMIOS.c_cc[VSUSP]' holds the character itself.

     The SUSP (suspend) character is recognized only if the
     implementation supports job control (*note Job Control::.).  It
     causes a `SIGTSTP' signal to be sent to all processes in the
     foreground job associated with the terminal.  The SUSP character
     itself is then discarded.  *Note Signal Handling::, for more
     information about signals.

     Typically, the SUSP character is `C-z'.

   Few applications disable the normal interpretation of the SUSP
character.  If your program does this, it should provide some other
mechanism for the user to stop the job.  When the user invokes this
mechanism, the program should send a `SIGTSTP' signal to the process
group of the process, not just to the process itself.  *Note Signaling
Another Process::.

 - Macro: int VDSUSP
     This is the subscript for the DSUSP character in the special
     control character array.  `TERMIOS.c_cc[VDSUSP]' holds the
     character itself.

     The DSUSP (suspend) character is recognized only if the
     implementation supports job control (*note Job Control::.).  It
     sends a `SIGTSTP' signal, like the SUSP character, but not right
     away--only when the program tries to read it as input.  Not all
     systems with job control support DSUSP; only BSD-compatible
     systems (including the GNU system).

     *Note Signal Handling::, for more information about signals.

     Typically, the DSUSP character is `C-y'.


File: libc.info,  Node: Start/Stop Characters,  Next: Other Special,  Prev: Signal Characters,  Up: Special Characters

Special Characters for Flow Control
...................................

   These special characters may be active in either canonical or
noncanonical input mode, but their use is controlled by the flags
`IXON' and `IXOFF' (*note Input Modes::.).

 - Macro: int VSTART
     This is the subscript for the START character in the special
     control character array.  `TERMIOS.c_cc[VSTART]' holds the
     character itself.

     The START character is used to support the `IXON' and `IXOFF'
     input modes.  If `IXON' is set, receiving a START character resumes
     suspended output; the START character itself is discarded.  If
     `IXANY' is set, receiving any character at all resumes suspended
     output; the resuming character is not discarded unless it is the
     START character.  `IXOFF' is set, the system may also transmit
     START characters to the terminal.

     The usual value for the START character is `C-q'.  You may not be
     able to change this value--the hardware may insist on using `C-q'
     regardless of what you specify.

 - Macro: int VSTOP
     This is the subscript for the STOP character in the special control
     character array.  `TERMIOS.c_cc[VSTOP]' holds the character itself.

     The STOP character is used to support the `IXON' and `IXOFF' input
     modes.  If `IXON' is set, receiving a STOP character causes output
     to be suspended; the STOP character itself is discarded.  If
     `IXOFF' is set, the system may also transmit STOP characters to the
     terminal, to prevent the input queue from overflowing.

     The usual value for the STOP character is `C-s'.  You may not be
     able to change this value--the hardware may insist on using `C-s'
     regardless of what you specify.


File: libc.info,  Node: Other Special,  Prev: Start/Stop Characters,  Up: Special Characters

Other Special Characters
........................

   These special characters exist only in BSD systems and the GNU
system.

 - Macro: int VLNEXT
     This is the subscript for the LNEXT character in the special
     control character array.  `TERMIOS.c_cc[VLNEXT]' holds the
     character itself.

     The LNEXT character is recognized only when `IEXTEN' is set, but in
     both canonical and noncanonical mode.  It disables any special
     significance of the next character the user types.  Even if the
     character would normally perform some editing function or generate
     a signal, it is read as a plain character.  This is the analogue
     of the `C-q' command in Emacs.  "LNEXT" stands for "literal next."

     The LNEXT character is usually `C-v'.

 - Macro: int VDISCARD
     This is the subscript for the DISCARD character in the special
     control character array.  `TERMIOS.c_cc[VDISCARD]' holds the
     character itself.

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

 - Macro: int VSTATUS
     This is the subscript for the STATUS character in the special
     control character array.  `TERMIOS.c_cc[VSTATUS]' holds the
     character itself.

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

     The STATUS character is recognized only in canonical mode, and
     only if `NOKERNINFO' is not set.


File: libc.info,  Node: Noncanonical Input,  Prev: Special Characters,  Up: Terminal Modes

Noncanonical Input
------------------

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

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

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

 - Macro: int VMIN
     This is the subscript for the MIN slot in the `c_cc' array.  Thus,
     `TERMIOS.c_cc[VMIN]' is the value itself.

     The MIN slot is only meaningful in noncanonical input mode; it
     specifies the minimum number of bytes that must be available in the
     input queue in order for `read' to return.

 - Macro: int VTIME
     This is the subscript for the TIME slot in the `c_cc' array.  Thus,
     `TERMIOS.c_cc[VTIME]' is the value itself.

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

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

   * Both TIME and MIN are nonzero.

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

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

   * Both MIN and TIME are zero.

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

   * MIN is zero but TIME has a nonzero value.

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

   * TIME is zero but MIN has a nonzero value.

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

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

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

 - Function: int cfmakeraw (struct termios *TERMIOS-P)
     This function provides an easy way to set up `*TERMIOS-P' for what
     has traditionally been called "raw mode" in BSD.  This uses
     noncanonical input, and turns off most processing to give an
     unmodified channel to the terminal.

     It does exactly this:
            TERMIOS-P->c_iflag &= ~(IGNBRK|BRKINT|PARMRK|ISTRIP
                                          |INLCR|IGNCR|ICRNL|IXON);
            TERMIOS-P->c_oflag &= ~OPOST;
            TERMIOS-P->c_lflag &= ~(ECHO|ECHONL|ICANON|ISIG|IEXTEN);
            TERMIOS-P->c_cflag &= ~(CSIZE|PARENB);
            TERMIOS-P->c_cflag |= CS8;


File: libc.info,  Node: Line Control,  Next: Noncanon Example,  Prev: Terminal Modes,  Up: Low-Level Terminal Interface

Line Control Functions
======================

   These functions perform miscellaneous control actions on terminal
devices.  As regards terminal access, they are treated like doing
output: if any of these functions is used by a background process on its
controlling terminal, normally all processes in the process group are
sent a `SIGTTOU' signal.  The exception is if the calling process
itself is ignoring or blocking `SIGTTOU' signals, in which case the
operation is performed and no signal is sent.  *Note Job Control::.

 - Function: int tcsendbreak (int FILEDES, int DURATION)
     This function generates a break condition by transmitting a stream
     of zero bits on the terminal associated with the file descriptor
     FILEDES.  The duration of the break is controlled by the DURATION
     argument.  If zero, the duration is between 0.25 and 0.5 seconds.
     The meaning of a nonzero value depends on the operating system.

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

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

    `EBADF'
          The FILEDES is not a valid file descriptor.

    `ENOTTY'
          The FILEDES is not associated with a terminal device.

 - Function: int tcdrain (int FILEDES)
     The `tcdrain' function waits until all queued output to the
     terminal FILEDES has been transmitted.

     This function is a cancelation point in multi-threaded programs.
     This is a problem if the thread allocates some resources (like
     memory, file descriptors, semaphores or whatever) at the time
     `tcdrain' is called.  If the thread gets canceled these resources
     stay allocated until the program ends.  To avoid this calls to
     `tcdrain' should be protected using cancelation handlers.

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

    `EBADF'
          The FILEDES is not a valid file descriptor.

    `ENOTTY'
          The FILEDES is not associated with a terminal device.

    `EINTR'
          The operation was interrupted by delivery of a signal.  *Note
          Interrupted Primitives::.

 - Function: int tcflush (int FILEDES, int QUEUE)
     The `tcflush' function is used to clear the input and/or output
     queues associated with the terminal file FILEDES.  The QUEUE
     argument specifies which queue(s) to clear, and can be one of the
     following values:

    `TCIFLUSH'
          Clear any input data received, but not yet read.

    `TCOFLUSH'
          Clear any output data written, but not yet transmitted.

    `TCIOFLUSH'
          Clear both queued input and output.

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

    `EBADF'
          The FILEDES is not a valid file descriptor.

    `ENOTTY'
          The FILEDES is not associated with a terminal device.

    `EINVAL'
          A bad value was supplied as the QUEUE argument.

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

 - Function: int tcflow (int FILEDES, int ACTION)
     The `tcflow' function is used to perform operations relating to
     XON/XOFF flow control on the terminal file specified by FILEDES.

     The ACTION argument specifies what operation to perform, and can
     be one of the following values:

    `TCOOFF'
          Suspend transmission of output.

    `TCOON'
          Restart transmission of output.

    `TCIOFF'
          Transmit a STOP character.

    `TCION'
          Transmit a START character.

     For more information about the STOP and START characters, see
     *Note Special Characters::.

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

    `EBADF'
          The FILEDES is not a valid file descriptor.

    `ENOTTY'
          The FILEDES is not associated with a terminal device.

    `EINVAL'
          A bad value was supplied as the ACTION argument.


File: libc.info,  Node: Noncanon Example,  Next: Pseudo-Terminals,  Prev: Line Control,  Up: Low-Level Terminal Interface

Noncanonical Mode Example
=========================

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

     #include <unistd.h>
     #include <stdio.h>
     #include <stdlib.h>
     #include <termios.h>
     
     /* Use this variable to remember original terminal attributes. */
     
     struct termios saved_attributes;
     
     void
     reset_input_mode (void)
     {
       tcsetattr (STDIN_FILENO, TCSANOW, &saved_attributes);
     }
     
     void
     set_input_mode (void)
     {
       struct termios tattr;
       char *name;
     
       /* Make sure stdin is a terminal. */
       if (!isatty (STDIN_FILENO))
         {
           fprintf (stderr, "Not a terminal.\n");
           exit (EXIT_FAILURE);
         }
     
       /* Save the terminal attributes so we can restore them later. */
       tcgetattr (STDIN_FILENO, &saved_attributes);
       atexit (reset_input_mode);
     /* Set the funny terminal modes. */
       tcgetattr (STDIN_FILENO, &tattr);
       tattr.c_lflag &= ~(ICANON|ECHO); /* Clear ICANON and ECHO. */
       tattr.c_cc[VMIN] = 1;
       tattr.c_cc[VTIME] = 0;
       tcsetattr (STDIN_FILENO, TCSAFLUSH, &tattr);
     }
     
     int
     main (void)
     {
       char c;
     
       set_input_mode ();
     
       while (1)
         {
           read (STDIN_FILENO, &c, 1);
           if (c == '\004')          /* `C-d' */
             break;
           else
             putchar (c);
         }
     
       return EXIT_SUCCESS;
     }

   This program is careful to restore the original terminal modes before
exiting or terminating with a signal.  It uses the `atexit' function
(*note Cleanups on Exit::.) to make sure this is done by `exit'.

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


File: libc.info,  Node: Pseudo-Terminals,  Prev: Noncanon Example,  Up: Low-Level Terminal Interface

Pseudo-Terminals
================

   A "pseudo-terminal" is a special interprocess communication channel
that acts like a terminal.  One end of the channel is called the
"master" side or "master pseudo-terminal device", the other side is
called the "slave" side.  Data written to the master side is received
by the slave side as if it was the result of a user typing at an
ordinary terminal, and data written to the slave side is sent to the
master side as if it was written on an ordinary terminal.

   Pseudo terminals are the way programs like `xterm' and `emacs'
implement their terminal emulation functionality.

* Menu:

* Allocation::             Allocating a pseudo terminal.
* Pseudo-Terminal Pairs::  How to open both sides of a
                            pseudo-terminal in a single operation.


File: libc.info,  Node: Allocation,  Next: Pseudo-Terminal Pairs,  Up: Pseudo-Terminals

Allocating Pseudo-Terminals
---------------------------

   This subsection describes functions for allocating a pseudo-terminal,
and for making this pseudo-terminal available for actual use.  These
functions are declared in the header file `stdlib.h'.

 - Function: int getpt (void)
     The `getpt' function returns a new file descriptor for the next
     available master pseudo-terminal.  The normal return value from
     `getpt' is a non-negative integer file descriptor.  In the case of
     an error, a value of -1 is returned instead.  The following
     `errno' conditions are defined for this function:

    `ENOENT'
          There are no free master pseudo-terminals available.

     This function is a GNU extension.

 - Function: int grantpt (int FILEDES)
     The `grantpt' function changes the ownership and access permission
     of the slave pseudo-terminal device corresponding to the master
     pseudo-terminal device associated with the file descriptor
     FILEDES.  The owner is set from the real user ID of the calling
     process (*note Process Persona::.), and the group is set to a
     special group (typically "tty") or from the real group ID of the
     calling process.  The access permission is set such that the file
     is both readable and writable by the owner and only writable by
     the group.

     On some systems this function is implemented by invoking a special
     `setuid' root program (*note How Change Persona::.).  As a
     consequence, installing a signal handler for the `SIGCHLD' signal
     (*note Job Control Signals::.) may interfere with a call to
     `grantpt'.

     The normal return value from `grantpt' is 0; a value of -1 is
     returned in case of failure.  The following `errno' error
     conditions are defined for this function:

    `EBADF'
          The FILEDES argument is not a valid file descriptor.

    `ENINVAL'
          The FILEDES argument is not associated with a master
          pseudo-terminal device.

    `EACCESS'
          The slave pseudo-terminal device corresponding to the master
          associated with FILEDES could not be accessed.


 - Function: int unlockpt (int FILEDES)
     The `unlockpt' function unlocks the slave pseudo-terminal device
     corresponding to the master pseudo-terminal device associated with
     the file descriptor FILEDES.  On many systems, the slave can only
     be opened after unlocking, so portable applications should always
     call `unlockpt' before trying to open the slave.

     The normal return value from `unlockpt' is 0; a value of -1 is
     returned in case of failure.  The following `errno' error
     conditions are defined for this function:

    `EBADF'
          The FILEDES argument is not a valid file descriptor.

    `EINVAL'
          The FILEDES argument is not associated with a master
          pseudo-terminal device.

 - Function: char * ptsname (int FILEDES)
     If the file descriptor FILEDES is associated with a master
     pseudo-terminal device, the `ptsname' function returns a pointer
     to a statically-allocated, null-terminated string containing the
     file name of the associated slave pseudo-terminal file.  This
     string might be overwritten by subsequent calls to `ptsname'.

 - Function: int ptsname_r (int FILEDES, char *BUF, size_t LEN)
     The `ptsname_r' function is similar to the `ptsname' function
     except that it places its result into the user-specified buffer
     starting at BUF with length LEN.

     This function is a GNU extension.

   *Portability Note:* On System V derived systems, the file returned
by the `ptsname' and `ptsname_r' functions may be STREAMS-based, and
therefore require additional processing after opening before it
actually behaves as a pseudo terminal.

   Typical usage of these functions is illustrated by the following
example:
     int
     open_pty_pair (int *amaster, int *aslave)
     {
       int master, slave;
       char *name
     
       master = getpt ();
       if (master < 0)
         return 0;
     
       if (grantpt (master) < 0 || unlockpt (master) < 0)
         goto close_master;
       name = ptsname (master);
       if (name == NULL)
         goto close_master;
     
       slave = open (name, O_RDWR);
       if (slave == -1)
         goto close_master;
     
       if (isastream (slave))
         {
           if (ioctl (slave, I_PUSH, "ptem") < 0
               || ioctl (slave, I_PUSH, "ldterm") < 0)
             goto close_slave;
         }
     
       *amaster = master;
       *aslave = slave;
       return 1;
     
     close_slave:
       close (slave);
     
     close_master:
       close (master);
       return 0;
     }


File: libc.info,  Node: Pseudo-Terminal Pairs,  Prev: Allocation,  Up: Pseudo-Terminals

Opening a Pseudo-Terminal Pair
------------------------------

   These functions, derived from BSD, are available in the separate
`libutil' library, and declared in `pty.h'.

 - Function: int openpty (int *AMASTER, int *ASLAVE, char *NAME, struct
          termios *TERMP, struct winsize *WINP)
     This function allocates and opens a pseudo-terminal pair,
     returning the file descriptor for the master in *AMASTER, and the
     file descriptor for the slave in *ASLAVE.  If the argument NAME is
     not a null pointer, the file name of the slave pseudo-terminal
     device is stored in `*name'.  If TERMP is not a null pointer, the
     terminal attributes of the slave are set to the ones specified in
     the structure that TERMP points to (*note Terminal Modes::.).
     Likewise, if the WINP is not a null pointer, the screen size of
     the slave is set to the values specified in the structure that
     WINP points to.

     The normal return value from `openpty' is 0; a value of -1 is
     returned in case of failure.  The following `errno' conditions are
     defined for this function:

    `ENOENT'
          There are no free pseudo-terminal pairs available.

     *Warning:* Using the `openpty' function with NAME not set to
     `NULL' is *very dangerous* because it provides no protection
     against overflowing the string NAME.  You should use the `ttyname'
     function on the file descriptor returned in *SLAVE to find out the
     file name of the slave pseudo-terminal device instead.

 - Function: int forkpty (int *AMASTER, char *NAME, struct termios
          *TERMP, struct winsize *WINP)
     This function is similar to the `openpty' function, but in
     addition, forks a new process (*note Creating a Process::.) and
     makes the newly opened slave pseudo-terminal device the
     controlling terminal (*note Controlling Terminal::.) for the child
     process.

     If the operation is successful, there are then both parent and
     child processes and both see `forkpty' return, but with different
     values: it returns a value of 0 in the child process and returns
     the child's process ID in the parent process.

     If the allocation of a pseudo-terminal pair or the process creation
     failed, `forkpty' returns a value of -1 in the parent process.

     *Warning:* The `forkpty' function has the same problems with
     respect to the NAME argument as `openpty'.


File: libc.info,  Node: Mathematics,  Next: Arithmetic,  Prev: Low-Level Terminal Interface,  Up: Top

Mathematics
***********

   This chapter contains information about functions for performing
mathematical computations, such as trigonometric functions.  Most of
these functions have prototypes declared in the header file `math.h'.
The complex-valued functions are defined in `complex.h'.

   All mathematical functions which take a floating-point argument have
three variants, one each for `double', `float', and `long double'
arguments.  The `double' versions are mostly defined in ISO C 89.  The
`float' and `long double' versions are from the numeric extensions to C
included in ISO C 9X.

   Which of the three versions of a function should be used depends on
the situation.  For most calculations, the `float' functions are the
fastest.  On the other hand, the `long double' functions have the
highest precision.  `double' is somewhere in between.  It is usually
wise to pick the narrowest type that can accomodate your data.  Not all
machines have a distinct `long double' type; it may be the same as
`double'.

* Menu:

* Mathematical Constants::      Precise numeric values for often-used
                                 constants.
* Trig Functions::              Sine, cosine, tangent, and friends.
* Inverse Trig Functions::      Arcsine, arccosine, etc.
* Exponents and Logarithms::    Also pow and sqrt.
* Hyperbolic Functions::        sinh, cosh, tanh, etc.
* Special Functions::           Bessel, gamma, erf.
* Pseudo-Random Numbers::       Functions for generating pseudo-random
				 numbers.
* FP Function Optimizations::   Fast code or small code.


File: libc.info,  Node: Mathematical Constants,  Next: Trig Functions,  Up: Mathematics

Predefined Mathematical Constants
=================================

   The header `math.h' defines several useful mathematical constants.
All values are defined as preprocessor macros starting with `M_'.  The
values provided are:

`M_E'
     The base of natural logarithms.

`M_LOG2E'
     The logarithm to base `2' of `M_E'.

`M_LOG10E'
     The logarithm to base `10' of `M_E'.

`M_LN2'
     The natural logarithm of `2'.

`M_LN10'
     The natural logarithm of `10'.

`M_PI'
     Pi, the ratio of a circle's circumrefence to its diameter.

`M_PI_2'
     Pi divided by two.

`M_PI_4'
     Pi divided by four.

`M_1_PI'
     The reciprocal of pi (1/pi)

`M_2_PI'
     Two times the reciprocal of pi.

`M_2_SQRTPI'
     Two times the reciprocal of the square root of pi.

`M_SQRT2'
     The square root of two.

`M_SQRT1_2'
     The reciprocal of the square root of two (also the square root of
     1/2).

   These constants come from the Unix98 standard and were also
available in 4.4BSD; therefore, they are only defined if `_BSD_SOURCE'
or `_XOPEN_SOURCE=500', or a more general feature select macro, is
defined.  The default set of features includes these constants.  *Note
Feature Test Macros::.

   All values are of type `double'.  As an extension, the GNU C library
also defines these constants with type `long double'.  The `long
double' macros have a lowercase `l' appended to their names: `M_El',
`M_PIl', and so forth.  These are only available if `_GNU_SOURCE' is
defined.

   *Note:* Some programs use a constant named `PI' which has the same
value as `M_PI'.  This constant is not standard; it may have appeared
in some old AT&T headers, and is mentioned in Stroustrup's book on C++.
It infringes on the user's name space, so the GNU C library does not
define it.  Fixing programs written to expect it is simple: replace
`PI' with `M_PI' throughout, or put `-DPI=M_PI' on the compiler command
line.


File: libc.info,  Node: Trig Functions,  Next: Inverse Trig Functions,  Prev: Mathematical Constants,  Up: Mathematics

Trigonometric Functions
=======================

   These are the familiar `sin', `cos', and `tan' functions.  The
arguments to all of these functions are in units of radians; recall
that pi radians equals 180 degrees.

   The math library normally defines `M_PI' to a `double' approximation
of pi.  If strict ISO and/or POSIX compliance are requested this
constant is not defined, but you can easily define it yourself:

     #define M_PI 3.14159265358979323846264338327

You can also compute the value of pi with the expression `acos (-1.0)'.

 - Function: double sin (double X)
 - Function: float sinf (float X)
 - Function: long double sinl (long double X)
     These functions return the sine of X, where X is given in radians.
     The return value is in the range `-1' to `1'.

 - Function: double cos (double X)
 - Function: float cosf (float X)
 - Function: long double cosl (long double X)
     These functions return the cosine of X, where X is given in
     radians.  The return value is in the range `-1' to `1'.

 - Function: double tan (double X)
 - Function: float tanf (float X)
 - Function: long double tanl (long double X)
     These functions return the tangent of X, where X is given in
     radians.

     Mathematically, the tangent function has singularities at odd
     multiples of pi/2.  If the argument X is too close to one of these
     singularities, `tan' will signal overflow.

   In many applications where `sin' and `cos' are used, the sine and
cosine of the same angle are needed at the same time.  It is more
efficient to compute them simultaneously, so the library provides a
function to do that.

 - Function: void sincos (double X, double *SINX, double *COSX)
 - Function: void sincosf (float X, float *SINX, float *COSX)
 - Function: void sincosl (long double X, long double *SINX, long
          double *COSX)
     These functions return the sine of X in `*SINX' and the cosine of
     X in `*COS', where X is given in radians.  Both values, `*SINX'
     and `*COSX', are in the range of `-1' to `1'.

     This function is a GNU extension.  Portable programs should be
     prepared to cope with its absence.

   ISO C 9x defines variants of the trig functions which work on
complex numbers.  The GNU C library provides these functions, but they
are only useful if your compiler supports the new complex types defined
by the standard.  (As of this writing GCC supports complex numbers, but
there are bugs in the implementation.)

 - Function: complex double csin (complex double Z)
 - Function: complex float csinf (complex float Z)
 - Function: complex long double csinl (complex long double Z)
     These functions return the complex sine of Z.  The mathematical
     definition of the complex sine is

     sin (z) = 1/(2*i) * (exp (z*i) - exp (-z*i)).

 - Function: complex double ccos (complex double Z)
 - Function: complex float ccosf (complex float Z)
 - Function: complex long double ccosl (complex long double Z)
     These functions return the complex cosine of Z.  The mathematical
     definition of the complex cosine is

     cos (z) = 1/2 * (exp (z*i) + exp (-z*i))

 - Function: complex double ctan (complex double Z)
 - Function: complex float ctanf (complex float Z)
 - Function: complex long double ctanl (complex long double Z)
     These functions return the complex tangent of Z.  The mathematical
     definition of the complex tangent is

     tan (z) = -i * (exp (z*i) - exp (-z*i)) / (exp (z*i) + exp (-z*i))

     The complex tangent has poles at pi/2 + 2n, where n is an integer.
     `ctan' may signal overflow if Z is too close to a pole.


File: libc.info,  Node: Inverse Trig Functions,  Next: Exponents and Logarithms,  Prev: Trig Functions,  Up: Mathematics

Inverse Trigonometric Functions
===============================

   These are the usual arc sine, arc cosine and arc tangent functions,
which are the inverses of the sine, cosine and tangent functions,
respectively.

 - Function: double asin (double X)
 - Function: float asinf (float X)
 - Function: long double asinl (long double X)
     These functions compute the arc sine of X--that is, the value whose
     sine is X.  The value is in units of radians.  Mathematically,
     there are infinitely many such values; the one actually returned
     is the one between `-pi/2' and `pi/2' (inclusive).

     The arc sine function is defined mathematically only over the
     domain `-1' to `1'.  If X is outside the domain, `asin' signals a
     domain error.

 - Function: double acos (double X)
 - Function: float acosf (float X)
 - Function: long double acosl (long double X)
     These functions compute the arc cosine of X--that is, the value
     whose cosine is X.  The value is in units of radians.
     Mathematically, there are infinitely many such values; the one
     actually returned is the one between `0' and `pi' (inclusive).

     The arc cosine function is defined mathematically only over the
     domain `-1' to `1'.  If X is outside the domain, `acos' signals a
     domain error.

 - Function: double atan (double X)
 - Function: float atanf (float X)
 - Function: long double atanl (long double X)
     These functions compute the arc tangent of X--that is, the value
     whose tangent is X.  The value is in units of radians.
     Mathematically, there are infinitely many such values; the one
     actually returned is the one between `-pi/2' and `pi/2'
     (inclusive).

 - Function: double atan2 (double Y, double X)
 - Function: float atan2f (float Y, float X)
 - Function: long double atan2l (long double Y, long double X)
     This function computes the arc tangent of Y/X, but the signs of
     both arguments are used to determine the quadrant of the result,
     and X is permitted to be zero.  The return value is given in
     radians and is in the range `-pi' to `pi', inclusive.

     If X and Y are coordinates of a point in the plane, `atan2'
     returns the signed angle between the line from the origin to that
     point and the x-axis.  Thus, `atan2' is useful for converting
     Cartesian coordinates to polar coordinates.  (To compute the
     radial coordinate, use `hypot'; see *Note Exponents and
     Logarithms::.)

     If both X and Y are zero, `atan2' returns zero.

   ISO C 9x defines complex versions of the inverse trig functions.

 - Function: complex double casin (complex double Z)
 - Function: complex float casinf (complex float Z)
 - Function: complex long double casinl (complex long double Z)
     These functions compute the complex arc sine of Z--that is, the
     value whose sine is Z.  The value returned is in radians.

     Unlike the real-valued functions, `casin' is defined for all
     values of Z.

 - Function: complex double cacos (complex double Z)
 - Function: complex float cacosf (complex float Z)
 - Function: complex long double cacosl (complex long double Z)
     These functions compute the complex arc cosine of Z--that is, the
     value whose cosine is Z.  The value returned is in radians.

     Unlike the real-valued functions, `cacos' is defined for all
     values of Z.

 - Function: complex double catan (complex double Z)
 - Function: complex float catanf (complex float Z)
 - Function: complex long double catanl (complex long double Z)
     These functions compute the complex arc tangent of Z--that is, the
     value whose tangent is Z.  The value is in units of radians.

