   This file documents the GNU C library.

   This is Edition 0.07 DRAFT, last updated 4 Oct 1996, of `The GNU C
Library Reference Manual', for Version 2.00 Beta.

   Copyright (C) 1993, '94, '95, '96 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.

Standard Environment Variables
------------------------------

   These environment variables have standard meanings.  This doesn't
mean that they are always present in the environment; but if these
variables *are* present, they have these meanings.  You shouldn't try
to use these environment variable names for some other purpose.

`HOME'
     This is a string representing the user's "home directory", or
     initial default working directory.

     The user can set `HOME' to any value.  If you need to make sure to
     obtain the proper home directory for a particular user, you should
     not use `HOME'; instead, look up the user's name in the user
     database (see User Database.).

     For most purposes, it is better to use `HOME', precisely because
     this lets the user specify the value.

`LOGNAME'
     This is the name that the user used to log in.  Since the value in
     the environment can be tweaked arbitrarily, this is not a reliable
     way to identify the user who is running a process; a function like
     `getlogin' (see Who Logged In.) is better for that purpose.

     For most purposes, it is better to use `LOGNAME', precisely because
     this lets the user specify the value.

`PATH'
     A "path" is a sequence of directory names which is used for
     searching for a file.  The variable `PATH' holds a path used for
     searching for programs to be run.

     The `execlp' and `execvp' functions (see Executing a File.)
     use this environment variable, as do many shells and other
     utilities which are implemented in terms of those functions.

     The syntax of a path is a sequence of directory names separated by
     colons.  An empty string instead of a directory name stands for the
     current directory (see Working Directory.).

     A typical value for this environment variable might be a string
     like:

          :/bin:/etc:/usr/bin:/usr/new/X11:/usr/new:/usr/local/bin

     This means that if the user tries to execute a program named `foo',
     the system will look for files named `foo', `/bin/foo',
     `/etc/foo', and so on.  The first of these files that exists is
     the one that is executed.

`TERM'
     This specifies the kind of terminal that is receiving program
     output.  Some programs can make use of this information to take
     advantage of special escape sequences or terminal modes supported
     by particular kinds of terminals.  Many programs which use the
     termcap library (see Find (termcap))
     use the `TERM' environment variable, for example.

`TZ'
     This specifies the time zone.  See TZ Variable, for
     information about the format of this string and how it is used.

`LANG'
     This specifies the default locale to use for attribute categories
     where neither `LC_ALL' nor the specific environment variable for
     that category is set.  See Locales, for more information about
     locales.

`LC_COLLATE'
     This specifies what locale to use for string sorting.

`LC_CTYPE'
     This specifies what locale to use for character sets and character
     classification.

`LC_MONETARY'
     This specifies what locale to use for formatting monetary values.

`LC_NUMERIC'
     This specifies what locale to use for formatting numbers.

`LC_TIME'
     This specifies what locale to use for formatting date/time values.

`_POSIX_OPTION_ORDER'
     If this environment variable is defined, it suppresses the usual
     reordering of command line arguments by `getopt'.  See Argument Syntax.

Program Termination
===================

   The usual way for a program to terminate is simply for its `main'
function to return.  The "exit status value" returned from the `main'
function is used to report information back to the process's parent
process or shell.

   A program can also terminate normally by calling the `exit' function.

   In addition, programs can be terminated by signals; this is
discussed in more detail in Signal Handling.  The `abort'
function causes a signal that kills the program.

Normal Termination
------------------

   A process terminates normally when the program calls `exit'.
Returning from `main' is equivalent to calling `exit', and the value
that `main' returns is used as the argument to `exit'.

 - Function: void exit (int STATUS)
     The `exit' function terminates the process with status STATUS.
     This function does not return.

   Normal termination causes the following actions:

  1. Functions that were registered with the `atexit' or `on_exit'
     functions are called in the reverse order of their registration.
     This mechanism allows your application to specify its own
     "cleanup" actions to be performed at program termination.
     Typically, this is used to do things like saving program state
     information in a file, or unlocking locks in shared data bases.

  2. All open streams are closed, writing out any buffered output data.
     See Closing Streams.  In addition, temporary files opened
     with the `tmpfile' function are removed; see Temporary Files.

  3. `_exit' is called, terminating the program.  See Termination Internals.

Exit Status
-----------

   When a program exits, it can return to the parent process a small
amount of information about the cause of termination, using the "exit
status".  This is a value between 0 and 255 that the exiting process
passes as an argument to `exit'.

   Normally you should use the exit status to report very broad
information about success or failure.  You can't provide a lot of
detail about the reasons for the failure, and most parent processes
would not want much detail anyway.

   There are conventions for what sorts of status values certain
programs should return.  The most common convention is simply 0 for
success and 1 for failure.  Programs that perform comparison use a
different convention: they use status 1 to indicate a mismatch, and
status 2 to indicate an inability to compare.  Your program should
follow an existing convention if an existing convention makes sense for
it.

   A general convention reserves status values 128 and up for special
purposes.  In particular, the value 128 is used to indicate failure to
execute another program in a subprocess.  This convention is not
universally obeyed, but it is a good idea to follow it in your programs.

   *Warning:* Don't try to use the number of errors as the exit status.
This is actually not very useful; a parent process would generally not
care how many errors occurred.  Worse than that, it does not work,
because the status value is truncated to eight bits.  Thus, if the
program tried to report 256 errors, the parent would receive a report
of 0 errors--that is, success.

   For the same reason, it does not work to use the value of `errno' as
the exit status--these can exceed 255.

   *Portability note:* Some non-POSIX systems use different conventions
for exit status values.  For greater portability, you can use the
macros `EXIT_SUCCESS' and `EXIT_FAILURE' for the conventional status
value for success and failure, respectively.  They are declared in the
file `stdlib.h'.

 - Macro: int EXIT_SUCCESS
     This macro can be used with the `exit' function to indicate
     successful program completion.

     On POSIX systems, the value of this macro is `0'.  On other
     systems, the value might be some other (possibly non-constant)
     integer expression.

 - Macro: int EXIT_FAILURE
     This macro can be used with the `exit' function to indicate
     unsuccessful program completion in a general sense.

     On POSIX systems, the value of this macro is `1'.  On other
     systems, the value might be some other (possibly non-constant)
     integer expression.  Other nonzero status values also indicate
     future.  Certain programs use different nonzero status values to
     indicate particular kinds of "non-success".  For example, `diff'
     uses status value `1' to mean that the files are different, and
     `2' or more to mean that there was difficulty in opening the files.

Cleanups on Exit
----------------

   Your program can arrange to run its own cleanup functions if normal
termination happens.  If you are writing a library for use in various
application programs, then it is unreliable to insist that all
applications call the library's cleanup functions explicitly before
exiting.  It is much more robust to make the cleanup invisible to the
application, by setting up a cleanup function in the library itself
using `atexit' or `on_exit'.

 - Function: int atexit (void (*FUNCTION) (void))
     The `atexit' function registers the function FUNCTION to be called
     at normal program termination.  The FUNCTION is called with no
     arguments.

     The return value from `atexit' is zero on success and nonzero if
     the function cannot be registered.

 - Function: int on_exit (void (*FUNCTION)(int STATUS, void *ARG), void
          *ARG)
     This function is a somewhat more powerful variant of `atexit'.  It
     accepts two arguments, a function FUNCTION and an arbitrary
     pointer ARG.  At normal program termination, the FUNCTION is
     called with two arguments:  the STATUS value passed to `exit', and
     the ARG.

     This function is included in the GNU C library only for
     compatibility for SunOS, and may not be supported by other
     implementations.

   Here's a trivial program that illustrates the use of `exit' and
`atexit':

     #include <stdio.h>
     #include <stdlib.h>

     void
     bye (void)
     {
       puts ("Goodbye, cruel world....");
     }

     int
     main (void)
     {
       atexit (bye);
       exit (EXIT_SUCCESS);
     }

When this program is executed, it just prints the message and exits.

Aborting a Program
------------------

   You can abort your program using the `abort' function.  The prototype
for this function is in `stdlib.h'.

 - Function: void abort (void)
     The `abort' function causes abnormal program termination.  This
     does not execute cleanup functions registered with `atexit' or
     `on_exit'.

     This function actually terminates the process by raising a
     `SIGABRT' signal, and your program can include a handler to
     intercept this signal; see Signal Handling.

   *Future Change Warning:* Proposed Federal censorship regulations may
prohibit us from giving you information about the possibility of
calling this function.  We would be required to say that this is not an
acceptable way of terminating a program.

Termination Internals
---------------------

   The `_exit' function is the primitive used for process termination
by `exit'.  It is declared in the header file `unistd.h'.

 - Function: void _exit (int STATUS)
     The `_exit' function is the primitive for causing a process to
     terminate with status STATUS.  Calling this function does not
     execute cleanup functions registered with `atexit' or `on_exit'.

   When a process terminates for any reason--either by an explicit
termination call, or termination as a result of a signal--the following
things happen:

   * All open file descriptors in the process are closed.  See
     Low-Level I/O.  Note that streams are not flushed automatically
     when the process terminates; see I/O on Streams.

   * The low-order 8 bits of the return status code are saved to be
     reported back to the parent process via `wait' or `waitpid'; see
     Process Completion.

   * Any child processes of the process being terminated are assigned a
     new parent process.  (On most systems, including GNU, this is the
     `init' process, with process ID 1.)

   * A `SIGCHLD' signal is sent to the parent process.

   * If the process is a session leader that has a controlling
     terminal, then a `SIGHUP' signal is sent to each process in the
     foreground job, and the controlling terminal is disassociated from
     that session.  See Job Control.

   * If termination of a process causes a process group to become
     orphaned, and any member of that process group is stopped, then a
     `SIGHUP' signal and a `SIGCONT' signal are sent to each process in
     the group.  See Job Control.

Processes
*********

   "Processes" are the primitive units for allocation of system
resources.  Each process has its own address space and (usually) one
thread of control.  A process executes a program; you can have multiple
processes executing the same program, but each process has its own copy
of the program within its own address space and executes it
independently of the other copies.

   Processes are organized hierarchically.  Each process has a "parent
process" which explicitly arranged to create it.  The processes created
by a given parent are called its "child processes".  A child inherits
many of its attributes from the parent process.

   This chapter describes how a program can create, terminate, and
control child processes.  Actually, there are three distinct operations
involved: creating a new child process, causing the new process to
execute a program, and coordinating the completion of the child process
with the original program.

   The `system' function provides a simple, portable mechanism for
running another program; it does all three steps automatically.  If you
need more control over the details of how this is done, you can use the
primitive functions to do each step individually instead.

Running a Command
=================

   The easy way to run another program is to use the `system' function.
This function does all the work of running a subprogram, but it
doesn't give you much control over the details: you have to wait until
the subprogram terminates before you can do anything else.

 - Function: int system (const char *COMMAND)
     This function executes COMMAND as a shell command.  In the GNU C
     library, it always uses the default shell `sh' to run the command.
     In particular, it searches the directories in `PATH' to find
     programs to execute.  The return value is `-1' if it wasn't
     possible to create the shell process, and otherwise is the status
     of the shell process.  See Process Completion, for details on
     how this status code can be interpreted.

     The `system' function is declared in the header file `stdlib.h'.

   *Portability Note:* Some C implementations may not have any notion
of a command processor that can execute other programs.  You can
determine whether a command processor exists by executing
`system (NULL)'; if the return value is nonzero, a command processor is
available.

   The `popen' and `pclose' functions (see Pipe to a Subprocess.)
are closely related to the `system' function.  They allow the parent
process to communicate with the standard input and output channels of
the command being executed.

Process Creation Concepts
=========================

   This section gives an overview of processes and of the steps
involved in creating a process and making it run another program.

   Each process is named by a "process ID" number.  A unique process ID
is allocated to each process when it is created.  The "lifetime" of a
process ends when its termination is reported to its parent process; at
that time, all of the process resources, including its process ID, are
freed.

   Processes are created with the `fork' system call (so the operation
of creating a new process is sometimes called "forking" a process).
The "child process" created by `fork' is a copy of the original "parent
process", except that it has its own process ID.

   After forking a child process, both the parent and child processes
continue to execute normally.  If you want your program to wait for a
child process to finish executing before continuing, you must do this
explicitly after the fork operation, by calling `wait' or `waitpid'
(see Process Completion.).  These functions give you limited
information about why the child terminated--for example, its exit
status code.

   A newly forked child process continues to execute the same program as
its parent process, at the point where the `fork' call returns.  You
can use the return value from `fork' to tell whether the program is
running in the parent process or the child.

   Having several processes run the same program is only occasionally
useful.  But the child can execute another program using one of the
`exec' functions; see Executing a File.  The program that the
process is executing is called its "process image".  Starting execution
of a new program causes the process to forget all about its previous
process image; when the new program exits, the process exits too,
instead of returning to the previous process image.

Process Identification
======================

   The `pid_t' data type represents process IDs.  You can get the
process ID of a process by calling `getpid'.  The function `getppid'
returns the process ID of the parent of the current process (this is
also known as the "parent process ID").  Your program should include
the header files `unistd.h' and `sys/types.h' to use these functions.

 - Data Type: pid_t
     The `pid_t' data type is a signed integer type which is capable of
     representing a process ID.  In the GNU library, this is an `int'.

 - Function: pid_t getpid (void)
     The `getpid' function returns the process ID of the current
     process.

 - Function: pid_t getppid (void)
     The `getppid' function returns the process ID of the parent of the
     current process.

Creating a Process
==================

   The `fork' function is the primitive for creating a process.  It is
declared in the header file `unistd.h'.

 - Function: pid_t fork (void)
     The `fork' function creates a new process.

     If the operation is successful, there are then both parent and
     child processes and both see `fork' 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 process creation failed, `fork' returns a value of `-1' in the
     parent process.  The following `errno' error conditions are
     defined for `fork':

    `EAGAIN'
          There aren't enough system resources to create another
          process, or the user already has too many processes running.
          This means exceeding the `RLIMIT_NPROC' resource limit, which
          can usually be increased; see Limits on Resources..

    `ENOMEM'
          The process requires more space than the system can supply.

   The specific attributes of the child process that differ from the
parent process are:

   * The child process has its own unique process ID.

   * The parent process ID of the child process is the process ID of its
     parent process.

   * The child process gets its own copies of the parent process's open
     file descriptors.  Subsequently changing attributes of the file
     descriptors in the parent process won't affect the file
     descriptors in the child, and vice versa.  See Control Operations.
     However, the file position associated with each
     descriptor is shared by both processes; see File Position..

   * The elapsed processor times for the child process are set to zero;
     see Processor Time.

   * The child doesn't inherit file locks set by the parent process.
     See Control Operations.

   * The child doesn't inherit alarms set by the parent process.  See
     Setting an Alarm.

   * The set of pending signals (see Delivery of Signal.) for the
     child process is cleared.  (The child process inherits its mask of
     blocked signals and signal actions from the parent process.)

 - Function: pid_t vfork (void)
     The `vfork' function is similar to `fork' but on systems it is
     more efficient; however, there are restrictions you must follow to
     use it safely.

     While `fork' makes a complete copy of the calling process's
     address space and allows both the parent and child to execute
     independently, `vfork' does not make this copy.  Instead, the
     child process created with `vfork' shares its parent's address
     space until it calls exits or one of the `exec' functions.  In the
     meantime, the parent process suspends execution.

     You must be very careful not to allow the child process created
     with `vfork' to modify any global data or even local variables
     shared with the parent.  Furthermore, the child process cannot
     return from (or do a long jump out of) the function that called
     `vfork'!  This would leave the parent process's control
     information very confused.  If in doubt, use `fork' instead.

     Some operating systems don't really implement `vfork'.  The GNU C
     library permits you to use `vfork' on all systems, but actually
     executes `fork' if `vfork' isn't available.  If you follow the
     proper precautions for using `vfork', your program will still work
     even if the system uses `fork' instead.

Executing a File
================

   This section describes the `exec' family of functions, for executing
a file as a process image.  You can use these functions to make a child
process execute a new program after it has been forked.

   The functions in this family differ in how you specify the arguments,
but otherwise they all do the same thing.  They are declared in the
header file `unistd.h'.

 - Function: int execv (const char *FILENAME, char *const ARGV[])
     The `execv' function executes the file named by FILENAME as a new
     process image.

     The ARGV argument is an array of null-terminated strings that is
     used to provide a value for the `argv' argument to the `main'
     function of the program to be executed.  The last element of this
     array must be a null pointer.  By convention, the first element of
     this array is the file name of the program sans directory names.
     See Program Arguments, for full details on how programs can
     access these arguments.

     The environment for the new process image is taken from the
     `environ' variable of the current process image; see
     Environment Variables, for information about environments.

 - Function: int execl (const char *FILENAME, const char *ARG0, ...)
     This is similar to `execv', but the ARGV strings are specified
     individually instead of as an array.  A null pointer must be
     passed as the last such argument.

 - Function: int execve (const char *FILENAME, char *const ARGV[], char
          *const ENV[])
     This is similar to `execv', but permits you to specify the
     environment for the new program explicitly as the ENV argument.
     This should be an array of strings in the same format as for the
     `environ' variable; see Environment Access.

 - Function: int execle (const char *FILENAME, const char *ARG0, char
          *const ENV[], ...)
     This is similar to `execl', but permits you to specify the
     environment for the new program explicitly.  The environment
     argument is passed following the null pointer that marks the last
     ARGV argument, and should be an array of strings in the same
     format as for the `environ' variable.

 - Function: int execvp (const char *FILENAME, char *const ARGV[])
     The `execvp' function is similar to `execv', except that it
     searches the directories listed in the `PATH' environment variable
     (see Standard Environment.) to find the full file name of a
     file from FILENAME if FILENAME does not contain a slash.

     This function is useful for executing system utility programs,
     because it looks for them in the places that the user has chosen.
     Shells use it to run the commands that users type.

 - Function: int execlp (const char *FILENAME, const char *ARG0, ...)
     This function is like `execl', except that it performs the same
     file name searching as the `execvp' function.

   The size of the argument list and environment list taken together
must not be greater than `ARG_MAX' bytes.  See General Limits.  In
the GNU system, the size (which compares against `ARG_MAX') includes,
for each string, the number of characters in the string, plus the size
of a `char *', plus one, rounded up to a multiple of the size of a
`char *'.  Other systems may have somewhat different rules for counting.

   These functions normally don't return, since execution of a new
program causes the currently executing program to go away completely.
A value of `-1' is returned in the event of a failure.  In addition to
the usual file name errors (see File Name Errors.), the following
`errno' error conditions are defined for these functions:

`E2BIG'
     The combined size of the new program's argument list and
     environment list is larger than `ARG_MAX' bytes.  The GNU system
     has no specific limit on the argument list size, so this error
     code cannot result, but you may get `ENOMEM' instead if the
     arguments are too big for available memory.

`ENOEXEC'
     The specified file can't be executed because it isn't in the right
     format.

`ENOMEM'
     Executing the specified file requires more storage than is
     available.

   If execution of the new file succeeds, it updates the access time
field of the file as if the file had been read.  See File Times,
for more details about access times of files.

   The point at which the file is closed again is not specified, but is
at some point before the process exits or before another process image
is executed.

   Executing a new process image completely changes the contents of
memory, copying only the argument and environment strings to new
locations.  But many other attributes of the process are unchanged:

   * The process ID and the parent process ID.  See Process Creation Concepts.

   * Session and process group membership.  See Concepts of Job Control.

   * Real user ID and group ID, and supplementary group IDs.  See
     Process Persona.

   * Pending alarms.  See Setting an Alarm.

   * Current working directory and root directory.  See Working Directory.
     In the GNU system, the root directory is not copied
     when executing a setuid program; instead the system default root
     directory is used for the new program.

   * File mode creation mask.  See Setting Permissions.

   * Process signal mask; see Process Signal Mask.

   * Pending signals; see Blocking Signals.

   * Elapsed processor time associated with the process; see
     Processor Time.

   If the set-user-ID and set-group-ID mode bits of the process image
file are set, this affects the effective user ID and effective group ID
(respectively) of the process.  These concepts are discussed in detail
in Process Persona.

   Signals that are set to be ignored in the existing process image are
also set to be ignored in the new process image.  All other signals are
set to the default action in the new process image.  For more
information about signals, see Signal Handling.

   File descriptors open in the existing process image remain open in
the new process image, unless they have the `FD_CLOEXEC'
(close-on-exec) flag set.  The files that remain open inherit all
attributes of the open file description from the existing process image,
including file locks.  File descriptors are discussed in
Low-Level I/O.

   Streams, by contrast, cannot survive through `exec' functions,
because they are located in the memory of the process itself.  The new
process image has no streams except those it creates afresh.  Each of
the streams in the pre-`exec' process image has a descriptor inside it,
and these descriptors do survive through `exec' (provided that they do
not have `FD_CLOEXEC' set).  The new process image can reconnect these
to new streams using `fdopen' (see Descriptors and Streams.).

Process Completion
==================

   The functions described in this section are used to wait for a child
process to terminate or stop, and determine its status.  These functions
are declared in the header file `sys/wait.h'.

 - Function: pid_t waitpid (pid_t PID, int *STATUS-PTR, int OPTIONS)
     The `waitpid' function is used to request status information from a
     child process whose process ID is PID.  Normally, the calling
     process is suspended until the child process makes status
     information available by terminating.

     Other values for the PID argument have special interpretations.  A
     value of `-1' or `WAIT_ANY' requests status information for any
     child process; a value of `0' or `WAIT_MYPGRP' requests
     information for any child process in the same process group as the
     calling process; and any other negative value - PGID requests
     information for any child process whose process group ID is PGID.

     If status information for a child process is available
     immediately, this function returns immediately without waiting.
     If more than one eligible child process has status information
     available, one of them is chosen randomly, and its status is
     returned immediately.  To get the status from the other eligible
     child processes, you need to call `waitpid' again.

     The OPTIONS argument is a bit mask.  Its value should be the
     bitwise OR (that is, the `|' operator) of zero or more of the
     `WNOHANG' and `WUNTRACED' flags.  You can use the `WNOHANG' flag
     to indicate that the parent process shouldn't wait; and the
     `WUNTRACED' flag to request status information from stopped
     processes as well as processes that have terminated.

     The status information from the child process is stored in the
     object that STATUS-PTR points to, unless STATUS-PTR is a null
     pointer.

     The return value is normally the process ID of the child process
     whose status is reported.  If the `WNOHANG' option was specified
     and no child process is waiting to be noticed, the value is zero.
     A value of `-1' is returned in case of error.  The following
     `errno' error conditions are defined for this function:

    `EINTR'
          The function was interrupted by delivery of a signal to the
          calling process.  See Interrupted Primitives.

    `ECHILD'
          There are no child processes to wait for, or the specified PID
          is not a child of the calling process.

    `EINVAL'
          An invalid value was provided for the OPTIONS argument.

   These symbolic constants are defined as values for the PID argument
to the `waitpid' function.

`WAIT_ANY'
     This constant macro (whose value is `-1') specifies that `waitpid'
     should return status information about any child process.

`WAIT_MYPGRP'
     This constant (with value `0') specifies that `waitpid' should
     return status information about any child process in the same
     process group as the calling process.

   These symbolic constants are defined as flags for the OPTIONS
argument to the `waitpid' function.  You can bitwise-OR the flags
together to obtain a value to use as the argument.

`WNOHANG'
     This flag specifies that `waitpid' should return immediately
     instead of waiting, if there is no child process ready to be
     noticed.

`WUNTRACED'
     This flag specifies that `waitpid' should report the status of any
     child processes that have been stopped as well as those that have
     terminated.

 - Function: pid_t wait (int *STATUS-PTR)
     This is a simplified version of `waitpid', and is used to wait
     until any one child process terminates.  The call:

          wait (&status)

     is exactly equivalent to:

          waitpid (-1, &status, 0)

 - Function: pid_t wait4 (pid_t PID, int *STATUS-PTR, int OPTIONS,
          struct rusage *USAGE)
     If USAGE is a null pointer, `wait4' is equivalent to `waitpid
     (PID, STATUS-PTR, OPTIONS)'.

     If USAGE is not null, `wait4' stores usage figures for the child
     process in `*RUSAGE' (but only if the child has terminated, not if
     it has stopped).  See Resource Usage.

     This function is a BSD extension.

   Here's an example of how to use `waitpid' to get the status from all
child processes that have terminated, without ever waiting.  This
function is designed to be a handler for `SIGCHLD', the signal that
indicates that at least one child process has terminated.

     void
     sigchld_handler (int signum)
     {
       int pid;
       int status;
       while (1)
         {
           pid = waitpid (WAIT_ANY, &status, WNOHANG);
           if (pid < 0)
             {
               perror ("waitpid");
               break;
             }
           if (pid == 0)
             break;
           notice_termination (pid, status);
         }
     }

Process Completion Status
=========================

   If the exit status value (see Program Termination.) of the child
process is zero, then the status value reported by `waitpid' or `wait'
is also zero.  You can test for other kinds of information encoded in
the returned status value using the following macros.  These macros are
defined in the header file `sys/wait.h'.

 - Macro: int WIFEXITED (int STATUS)
     This macro returns a nonzero value if the child process terminated
     normally with `exit' or `_exit'.

 - Macro: int WEXITSTATUS (int STATUS)
     If `WIFEXITED' is true of STATUS, this macro returns the low-order
     8 bits of the exit status value from the child process.  See
     Exit Status.

 - Macro: int WIFSIGNALED (int STATUS)
     This macro returns a nonzero value if the child process terminated
     because it received a signal that was not handled.  See Signal Handling.

 - Macro: int WTERMSIG (int STATUS)
     If `WIFSIGNALED' is true of STATUS, this macro returns the signal
     number of the signal that terminated the child process.

 - Macro: int WCOREDUMP (int STATUS)
     This macro returns a nonzero value if the child process terminated
     and produced a core dump.

 - Macro: int WIFSTOPPED (int STATUS)
     This macro returns a nonzero value if the child process is stopped.

 - Macro: int WSTOPSIG (int STATUS)
     If `WIFSTOPPED' is true of STATUS, this macro returns the signal
     number of the signal that caused the child process to stop.

BSD Process Wait Functions
==========================

   The GNU library also provides these related facilities for
compatibility with BSD Unix.  BSD uses the `union wait' data type to
represent status values rather than an `int'.  The two representations
are actually interchangeable; they describe the same bit patterns.  The
GNU C Library defines macros such as `WEXITSTATUS' so that they will
work on either kind of object, and the `wait' function is defined to
accept either type of pointer as its STATUS-PTR argument.

   These functions are declared in `sys/wait.h'.

 - Data Type: union wait
     This data type represents program termination status values.  It
     has the following members:

    `int w_termsig'
          The value of this member is the same as the result of the
          `WTERMSIG' macro.

    `int w_coredump'
          The value of this member is the same as the result of the
          `WCOREDUMP' macro.

    `int w_retcode'
          The value of this member is the same as the result of the
          `WEXITSTATUS' macro.

    `int w_stopsig'
          The value of this member is the same as the result of the
          `WSTOPSIG' macro.

     Instead of accessing these members directly, you should use the
     equivalent macros.

   The `wait3' function is the predecessor to `wait4', which is more
flexible.  `wait3' is now obsolete.

 - Function: pid_t wait3 (union wait *STATUS-PTR, int OPTIONS, struct
          rusage *USAGE)
     If USAGE is a null pointer, `wait3' is equivalent to `waitpid (-1,
     STATUS-PTR, OPTIONS)'.

     If USAGE is not null, `wait3' stores usage figures for the child
     process in `*RUSAGE' (but only if the child has terminated, not if
     it has stopped).  See Resource Usage.

Process Creation Example
========================

   Here is an example program showing how you might write a function
similar to the built-in `system'.  It executes its COMMAND argument
using the equivalent of `sh -c COMMAND'.

     #include <stddef.h>
     #include <stdlib.h>
     #include <unistd.h>
     #include <sys/types.h>
     #include <sys/wait.h>

     /* Execute the command using this shell program.  */
     #define SHELL "/bin/sh"
     int
     my_system (const char *command)
     {
       int status;
       pid_t pid;

       pid = fork ();
       if (pid == 0)
         {
           /* This is the child process.  Execute the shell command. */
           execl (SHELL, SHELL, "-c", command, NULL);
           _exit (EXIT_FAILURE);
         }
       else if (pid < 0)
         /* The fork failed.  Report failure.  */
         status = -1;
       else
         /* This is the parent process.  Wait for the child to complete.  */
         if (waitpid (pid, &status, 0) != pid)
           status = -1;
       return status;
     }

   There are a couple of things you should pay attention to in this
example.

   Remember that the first `argv' argument supplied to the program
represents the name of the program being executed.  That is why, in the
call to `execl', `SHELL' is supplied once to name the program to
execute and a second time to supply a value for `argv[0]'.

   The `execl' call in the child process doesn't return if it is
successful.  If it fails, you must do something to make the child
process terminate.  Just returning a bad status code with `return'
would leave two processes running the original program.  Instead, the
right behavior is for the child process to report failure to its parent
process.

   Call `_exit' to accomplish this.  The reason for using `_exit'
instead of `exit' is to avoid flushing fully buffered streams such as
`stdout'.  The buffers of these streams probably contain data that was
copied from the parent process by the `fork', data that will be output
eventually by the parent process.  Calling `exit' in the child would
output the data twice.  See Termination Internals.

Job Control
***********

   "Job control" refers to the protocol for allowing a user to move
between multiple "process groups" (or "jobs") within a single "login
session".  The job control facilities are set up so that appropriate
behavior for most programs happens automatically and they need not do
anything special about job control.  So you can probably ignore the
material in this chapter unless you are writing a shell or login
program.

   You need to be familiar with concepts relating to process creation
(see Process Creation Concepts.) and signal handling (see Signal Handling.)
in order to understand this material presented in this
chapter.

Concepts of Job Control
=======================

   The fundamental purpose of an interactive shell is to read commands
from the user's terminal and create processes to execute the programs
specified by those commands.  It can do this using the `fork' (see
Creating a Process.) and `exec' (see Executing a File.) functions.

   A single command may run just one process--but often one command uses
several processes.  If you use the `|' operator in a shell command, you
explicitly request several programs in their own processes.  But even
if you run just one program, it can use multiple processes internally.
For example, a single compilation command such as `cc -c foo.c'
typically uses four processes (though normally only two at any given
time).  If you run `make', its job is to run other programs in separate
processes.

   The processes belonging to a single command are called a "process
group" or "job".  This is so that you can operate on all of them at
once.  For example, typing `C-c' sends the signal `SIGINT' to terminate
all the processes in the foreground process group.

   A "session" is a larger group of processes.  Normally all the
proccesses that stem from a single login belong to the same session.

   Every process belongs to a process group.  When a process is
created, it becomes a member of the same process group and session as
its parent process.  You can put it in another process group using the
`setpgid' function, provided the process group belongs to the same
session.

   The only way to put a process in a different session is to make it
the initial process of a new session, or a "session leader", using the
`setsid' function.  This also puts the session leader into a new
process group, and you can't move it out of that process group again.

   Usually, new sessions are created by the system login program, and
the session leader is the process running the user's login shell.

   A shell that supports job control must arrange to control which job
can use the terminal at any time.  Otherwise there might be multiple
jobs trying to read from the terminal at once, and confusion about which
process should receive the input typed by the user.  To prevent this,
the shell must cooperate with the terminal driver using the protocol
described in this chapter.

   The shell can give unlimited access to the controlling terminal to
only one process group at a time.  This is called the "foreground job"
on that controlling terminal.  Other process groups managed by the shell
that are executing without such access to the terminal are called
"background jobs".

   If a background job needs to read from its controlling terminal, it
is "stopped" by the terminal driver; if the `TOSTOP' mode is set,
likewise for writing.  The user can stop a foreground job by typing the
SUSP character (see Special Characters.) and a program can stop any
job by sending it a `SIGSTOP' signal.  It's the responsibility of the
shell to notice when jobs stop, to notify the user about them, and to
provide mechanisms for allowing the user to interactively continue
stopped jobs and switch jobs between foreground and background.

   See Access to the Terminal, for more information about I/O to the
controlling terminal,

Job Control is Optional
=======================

   Not all operating systems support job control.  The GNU system does
support job control, but if you are using the GNU library on some other
system, that system may not support job control itself.

   You can use the `_POSIX_JOB_CONTROL' macro to test at compile-time
whether the system supports job control.  See System Options.

   If job control is not supported, then there can be only one process
group per session, which behaves as if it were always in the foreground.
The functions for creating additional process groups simply fail with
the error code `ENOSYS'.

   The macros naming the various job control signals (see Job Control Signals.)
are defined even if job control is not supported.  However,
the system never generates these signals, and attempts to send a job
control signal or examine or specify their actions report errors or do
nothing.

Controlling Terminal of a Process
=================================

   One of the attributes of a process is its controlling terminal.
Child processes created with `fork' inherit the controlling terminal
from their parent process.  In this way, all the processes in a session
inherit the controlling terminal from the session leader.  A session
leader that has control of a terminal is called the "controlling
process" of that terminal.

   You generally do not need to worry about the exact mechanism used to
allocate a controlling terminal to a session, since it is done for you
by the system when you log in.

   An individual process disconnects from its controlling terminal when
it calls `setsid' to become the leader of a new session.  See Process Group Functions.

Access to the Controlling Terminal
==================================

   Processes in the foreground job of a controlling terminal have
unrestricted access to that terminal; background proesses do not.  This
section describes in more detail what happens when a process in a
background job tries to access its controlling terminal.

   When a process in a background job tries to read from its controlling
terminal, the process group is usually sent a `SIGTTIN' signal.  This
normally causes all of the processes in that group to stop (unless they
handle the signal and don't stop themselves).  However, if the reading
process is ignoring or blocking this signal, then `read' fails with an
`EIO' error instead.

   Similarly, when a process in a background job tries to write to its
controlling terminal, the default behavior is to send a `SIGTTOU'
signal to the process group.  However, the behavior is modified by the
`TOSTOP' bit of the local modes flags (see Local Modes.).  If this
bit is not set (which is the default), then writing to the controlling
terminal is always permitted without sending a signal.  Writing is also
permitted if the `SIGTTOU' signal is being ignored or blocked by the
writing process.

   Most other terminal operations that a program can do are treated as
reading or as writing.  (The description of each operation should say
which.)

   For more information about the primitive `read' and `write'
functions, see I/O Primitives.