   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, '97 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.

Example of Parsing Arguments with `getopt'
------------------------------------------

   Here is an example showing how `getopt' is typically used.  The key
points to notice are:

   * Normally, `getopt' is called in a loop.  When `getopt' returns
     `-1', indicating no more options are present, the loop terminates.

   * A `switch' statement is used to dispatch on the return value from
     `getopt'.  In typical use, each case just sets a variable that is
     used later in the program.

   * A second loop is used to process the remaining non-option
     arguments.

     #include <unistd.h>
     #include <stdio.h>

     int
     main (int argc, char **argv)
     {
       int aflag = 0;
       int bflag = 0;
       char *cvalue = NULL;
       int index;
       int c;

       opterr = 0;

     while ((c = getopt (argc, argv, "abc:")) != -1)
         switch (c)
           {
           case 'a':
             aflag = 1;
             break;
           case 'b':
             bflag = 1;
             break;
           case 'c':
             cvalue = optarg;
             break;
           case '?':
             if (isprint (optopt))
               fprintf (stderr, "Unknown option `-%c'.\n", optopt);
             else
               fprintf (stderr,
                        "Unknown option character `\\x%x'.\n",
                        optopt);
             return 1;
           default:
             abort ();
           }

     printf ("aflag = %d, bflag = %d, cvalue = %s\n", aflag, bflag, cvalue);

       for (index = optind; index < argc; index++)
         printf ("Non-option argument %s\n", argv[index]);
       return 0;
     }

   Here are some examples showing what this program prints with
different combinations of arguments:

     % testopt
     aflag = 0, bflag = 0, cvalue = (null)

     % testopt -a -b
     aflag = 1, bflag = 1, cvalue = (null)

     % testopt -ab
     aflag = 1, bflag = 1, cvalue = (null)

     % testopt -c foo
     aflag = 0, bflag = 0, cvalue = foo

     % testopt -cfoo
     aflag = 0, bflag = 0, cvalue = foo

     % testopt arg1
     aflag = 0, bflag = 0, cvalue = (null)
     Non-option argument arg1

     % testopt -a arg1
     aflag = 1, bflag = 0, cvalue = (null)
     Non-option argument arg1

     % testopt -c foo arg1
     aflag = 0, bflag = 0, cvalue = foo
     Non-option argument arg1

     % testopt -a -- -b
     aflag = 1, bflag = 0, cvalue = (null)
     Non-option argument -b

     % testopt -a -
     aflag = 1, bflag = 0, cvalue = (null)
     Non-option argument -

Parsing Long Options
--------------------

   To accept GNU-style long options as well as single-character options,
use `getopt_long' instead of `getopt'.  This function is declared in
`getopt.h', not `unistd.h'.  You should make every program accept long
options if it uses any options, for this takes little extra work and
helps beginners remember how to use the program.

 - Data Type: struct option
     This structure describes a single long option name for the sake of
     `getopt_long'.  The argument LONGOPTS must be an array of these
     structures, one for each long option.  Terminate the array with an
     element containing all zeros.

     The `struct option' structure has these fields:

    `const char *name'
          This field is the name of the option.  It is a string.

    `int has_arg'
          This field says whether the option takes an argument.  It is
          an integer, and there are three legitimate values:
          `no_argument', `required_argument' and `optional_argument'.

    `int *flag'
    `int val'
          These fields control how to report or act on the option when
          it occurs.

          If `flag' is a null pointer, then the `val' is a value which
          identifies this option.  Often these values are chosen to
          uniquely identify particular long options.

          If `flag' is not a null pointer, it should be the address of
          an `int' variable which is the flag for this option.  The
          value in `val' is the value to store in the flag to indicate
          that the option was seen.

 - Function: int getopt_long (int ARGC, char **ARGV, const char
          *SHORTOPTS, struct option *LONGOPTS, int *INDEXPTR)
     Decode options from the vector ARGV (whose length is ARGC).  The
     argument SHORTOPTS describes the short options to accept, just as
     it does in `getopt'.  The argument LONGOPTS describes the long
     options to accept (see above).

     When `getopt_long' encounters a short option, it does the same
     thing that `getopt' would do: it returns the character code for the
     option, and stores the options argument (if it has one) in
     `optarg'.

     When `getopt_long' encounters a long option, it takes actions based
     on the `flag' and `val' fields of the definition of that option.

     If `flag' is a null pointer, then `getopt_long' returns the
     contents of `val' to indicate which option it found.  You should
     arrange distinct values in the `val' field for options with
     different meanings, so you can decode these values after
     `getopt_long' returns.  If the long option is equivalent to a short
     option, you can use the short option's character code in `val'.

     If `flag' is not a null pointer, that means this option should just
     set a flag in the program.  The flag is a variable of type `int'
     that you define.  Put the address of the flag in the `flag' field.
     Put in the `val' field the value you would like this option to
     store in the flag.  In this case, `getopt_long' returns `0'.

     For any long option, `getopt_long' tells you the index in the array
     LONGOPTS of the options definition, by storing it into
     `*INDEXPTR'.  You can get the name of the option with
     `LONGOPTS[*INDEXPTR].name'.  So you can distinguish among long
     options either by the values in their `val' fields or by their
     indices.  You can also distinguish in this way among long options
     that set flags.

     When a long option has an argument, `getopt_long' puts the argument
     value in the variable `optarg' before returning.  When the option
     has no argument, the value in `optarg' is a null pointer.  This is
     how you can tell whether an optional argument was supplied.

     When `getopt_long' has no more options to handle, it returns `-1',
     and leaves in the variable `optind' the index in ARGV of the next
     remaining argument.

Example of Parsing Long Options
-------------------------------

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

     /* Flag set by `--verbose'. */
     static int verbose_flag;

     int
     main (argc, argv)
          int argc;
          char **argv;
     {
       int c;

       while (1)
         {
           static struct option long_options[] =
             {
               /* These options set a flag. */
               {"verbose", 0, &verbose_flag, 1},
               {"brief", 0, &verbose_flag, 0},
               /* These options don't set a flag.
                  We distinguish them by their indices. */
               {"add", 1, 0, 0},
               {"append", 0, 0, 0},
               {"delete", 1, 0, 0},
               {"create", 0, 0, 0},
               {"file", 1, 0, 0},
               {0, 0, 0, 0}
             };
           /* `getopt_long' stores the option index here. */
           int option_index = 0;

           c = getopt_long (argc, argv, "abc:d:",
                            long_options, &option_index);

           /* Detect the end of the options. */
           if (c == -1)
             break;

           switch (c)
             {
             case 0:
               /* If this option set a flag, do nothing else now. */
               if (long_options[option_index].flag != 0)
                 break;
               printf ("option %s", long_options[option_index].name);
               if (optarg)
                 printf (" with arg %s", optarg);
               printf ("\n");
               break;

             case 'a':
               puts ("option -a\n");
               break;

             case 'b':
               puts ("option -b\n");
               break;

             case 'c':
               printf ("option -c with value `%s'\n", optarg);
               break;

             case 'd':
               printf ("option -d with value `%s'\n", optarg);
               break;

             case '?':
               /* `getopt_long' already printed an error message. */
               break;

             default:
               abort ();
             }
         }

       /* Instead of reporting `--verbose'
          and `--brief' as they are encountered,
          we report the final status resulting from them. */
       if (verbose_flag)
         puts ("verbose flag is set");

       /* Print any remaining command line arguments (not options). */
       if (optind < argc)
         {
           printf ("non-option ARGV-elements: ");
           while (optind < argc)
             printf ("%s ", argv[optind++]);
           putchar ('\n');
         }

       exit (0);
     }

Parsing of Suboptions
---------------------

   Having a single level of options is sometimes not enough.  There
might be too many options which have to be available or a set of
options is closely related.

   For this case some programs use suboptions.  One of the most
prominent programs is certainly `mount'(8).  The `-o' option take one
argument which itself is a comma separated list of options.  To ease the
programming of code like this the function `getsubopt' is available.

 - Function: int getsubopt (char **OPTIONP, const char* const *TOKENS,
          char **VALUEP)
     The OPTIONP parameter must be a pointer to a variable containing
     the address of the string to process.  When the function returns
     the reference is updated to point to the next suboption or to the
     terminating `\0' character if there is no more suboption available.

     The TOKENS parameter references an array of strings containing the
     known suboptions.  All strings must be `\0' terminated and to mark
     the end a null pointer must be stored.  When `getsubopt' finds a
     possible legal suboption it compares it with all strings available
     in the TOKENS array and returns the index in the string as the
     indicator.

     In case the suboption has an associated value introduced by a `='
     character, a pointer to the value is returned in VALUEP.  The
     string is `\0' terminated.  If no argument is available VALUEP is
     set to the null pointer.  By doing this the caller can check
     whether a necessary value is given or whether no unexpected value
     is present.

     In case the next suboption in the string is not mentioned in the
     TOKENS array the starting address of the suboption including a
     possible value is returned in VALUEP and the return value of the
     function is `-1'.

Parsing of Suboptions Example
-----------------------------

   The code which might appear in the `mount'(8) program is a perfect
example of the use of `getsubopt':

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

     int do_all;
     const char *type;
     int read_size;
     int write_size;
     int read_only;

     enum
     {
       RO_OPTION = 0,
       RW_OPTION,
       READ_SIZE_OPTION,
       WRITE_SIZE_OPTION
     };

     const char *mount_opts[] =
     {
       [RO_OPTION] = "ro",
       [RW_OPTION] = "rw",
       [READ_SIZE_OPTION] = "rsize",
       [WRITE_SIZE_OPTION] = "wsize"
     };

     int
     main (int argc, char *argv[])
     {
       char *subopts, *value;
       int opt;

       while ((opt = getopt (argc, argv, "at:o:")) != -1)
         switch (opt)
           {
           case 'a':
             do_all = 1;
             break;
           case 't':
             type = optarg;
             break;
           case 'o':
             subopts = optarg;
             while (*subopts != '\0')
               switch (getsubopt (&subopts, mount_opts, &value))
                 {
                 case RO_OPTION:
                   read_only = 1;
                   break;
                 case RW_OPTION:
                   read_only = 0;
                   break;
                 case READ_SIZE_OPTION:
                   if (value == NULL)
                     abort ();
                   read_size = atoi (value);
                   break;
                 case WRITE_SIZE_OPTION:
                   if (value == NULL)
                     abort ();
                   write_size = atoi (value);
                   break;
                 default:
                   /* Unknown suboption. */
                   printf ("Unknown suboption `%s'\n", value);
                   break;
                 }
             break;
           default:
             abort ();
           }

       /* Do the real work. */

       return 0;
     }

Environment Variables
=====================

   When a program is executed, it receives information about the
context in which it was invoked in two ways.  The first mechanism uses
the ARGV and ARGC arguments to its `main' function, and is discussed in
Program Arguments.  The second mechanism uses "environment
variables" and is discussed in this section.

   The ARGV mechanism is typically used to pass command-line arguments
specific to the particular program being invoked.  The environment, on
the other hand, keeps track of information that is shared by many
programs, changes infrequently, and that is less frequently used.

   The environment variables discussed in this section are the same
environment variables that you set using assignments and the `export'
command in the shell.  Programs executed from the shell inherit all of
the environment variables from the shell.

   Standard environment variables are used for information about the
user's home directory, terminal type, current locale, and so on; you
can define additional variables for other purposes.  The set of all
environment variables that have values is collectively known as the
"environment".

   Names of environment variables are case-sensitive and must not
contain the character `='.  System-defined environment variables are
invariably uppercase.

   The values of environment variables can be anything that can be
represented as a string.  A value must not contain an embedded null
character, since this is assumed to terminate the string.

Environment Access
------------------

   The value of an environment variable can be accessed with the
`getenv' function.  This is declared in the header file `stdlib.h'.

 - Function: char * getenv (const char *NAME)
     This function returns a string that is the value of the environment
     variable NAME.  You must not modify this string.  In some non-Unix
     systems not using the GNU library, it might be overwritten by
     subsequent calls to `getenv' (but not by any other library
     function).  If the environment variable NAME is not defined, the
     value is a null pointer.

 - Function: int putenv (const char *STRING)
     The `putenv' function adds or removes definitions from the
     environment.  If the STRING is of the form `NAME=VALUE', the
     definition is added to the environment.  Otherwise, the STRING is
     interpreted as the name of an environment variable, and any
     definition for this variable in the environment is removed.

     The GNU library provides this function for compatibility with
     SVID; it may not be available in other systems.

   You can deal directly with the underlying representation of
environment objects to add more variables to the environment (for
example, to communicate with another program you are about to execute;
see Executing a File).

 - Variable: char ** environ
     The environment is represented as an array of strings.  Each
     string is of the format `NAME=VALUE'.  The order in which strings
     appear in the environment is not significant, but the same NAME
     must not appear more than once.  The last element of the array is
     a null pointer.

     This variable is declared in the header file `unistd.h'.

     If you just want to get the value of an environment variable, use
     `getenv'.

   Unix systems, and the GNU system, pass the initial value of
`environ' as the third argument to `main'.  See Program Arguments.

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
     failures.  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.).