This is libc.info, produced by makeinfo version 4.0 from 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.09 DRAFT, last updated 28 Aug 1999, of `The GNU C
Library Reference Manual', for Version 2.2 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: Standard Environment,  Prev: Environment Access,  Up: Environment Variables

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 (*note 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 program; a function like
     `getlogin' (*note 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 (*note 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 (*note 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 (*note Find: (termcap)Finding a Terminal
     Description.) use the `TERM' environment variable, for example.

`TZ'
     This specifies the time zone.  *Note 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.  *Note Locales::, for more information about
     locales.

`LC_ALL'
     If this environment variable is set it overrides the selection for
     all the locales done using the other `LC_*' environment variables.
     The value of the other `LC_*' environment variables is simply
     ignored in this case.

`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_MESSAGES'
     This specifies what locale to use for printing messages and to
     parse responses.

`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.

`NLSPATH'
     This specifies the directories in which the `catopen' function
     looks for message translation catalogs.

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


File: libc.info,  Node: System Calls,  Next: Program Termination,  Prev: Environment Variables,  Up: Program Basics

System Calls
============

   A system call is a request for service that a program makes of the
kernel.  The service is generally something that only the kernel has
the privilege to do, such as doing I/O.  Programmers don't normally
need to be concerned with system calls because there are functions in
the GNU C library to do virtually everything that system calls do.
These functions work by making system calls themselves.  For example,
there is a system call that changes the permissions of a file, but you
don't need to know about it because you can just use the GNU C
library's `chmod' function.

   System calls are sometimes called kernel calls.

   However, there are times when you want to make a system call
explicitly, and for that, the GNU C library provides the `syscall'
function.  `syscall' is harder to use and less portable than functions
like `chmod', but easier and more portable than coding the system call
in assembler instructions.

   `syscall' is most useful when you are working with a system call
which is special to your system or is newer than the GNU C library you
are using.  `syscall' is implemented in an entirely generic way; the
function does not know anything about what a particular system call
does or even if it is valid.

   The description of `syscall' in this section assumes a certain
protocol for system calls on the various platforms on which the GNU C
library runs.  That protocol is not defined by any strong authority, but
we won't describe it here either because anyone who is coding `syscall'
probably won't accept anything less than kernel and C library source
code as a specification of the interface between them anyway.

   `syscall' is declared in `unistd.h'.

 - Function: long int syscall (long int SYSNO, ...)
     `syscall' performs a generic system call.

     SYSNO is the system call number.  Each kind of system call is
     identified by a number.  Macros for all the possible system call
     numbers are defined in `sys/syscall.h'

     The remaining arguments are the arguments for the system call, in
     order, and their meanings depend on the kind of system call.  Each
     kind of system call has a definite number of arguments, from zero
     to five.  If you code more arguments than the system call takes,
     the extra ones to the right are ignored.

     The return value is the return value from the system call, unless
     the system call failed.  In that case, `syscall' returns `-1' and
     sets `errno' to an error code that the system call returned.  Note
     that system calls do not return `-1' when they succeed.

     If you specify an invalid SYSNO, `syscall' returns `-1' with
     `errno' = `ENOSYS'.

     Example:


          #include <unistd.h>
          #include <sys/syscall.h>
          #include <errno.h>
          
          ...
          
          int rc;
          
          rc = syscall(SYS_chmod, "/etc/passwd", 0444);
          
          if (rc == -1)
             fprintf(stderr, "chmod failed, errno = %d\n", errno);

     This, if all the compatibility stars are aligned, is equivalent to
     the following preferable code:


          #include <sys/types.h>
          #include <sys/stat.h>
          #include <errno.h>
          
          ...
          
          int rc;
          
          rc = chmod("/etc/passwd", 0444);
          if (rc == -1)
             fprintf(stderr, "chmod failed, errno = %d\n", errno);



File: libc.info,  Node: Program Termination,  Prev: System Calls,  Up: Program Basics

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 *Note Signal Handling::.  The `abort'
function causes a signal that kills the program.

* Menu:

* Normal Termination::          If a program calls `exit', a
                                 process terminates normally.
* Exit Status::                 The `exit status' provides information
                                 about why the process terminated.
* Cleanups on Exit::            A process can run its own cleanup
                                 functions upon normal termination.
* Aborting a Program::          The `abort' function causes
                                 abnormal program termination.
* Termination Internals::       What happens when a process terminates.


File: libc.info,  Node: Normal Termination,  Next: Exit Status,  Up: Program Termination

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

   A process terminates normally when its program signals it is done by
calling `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 tells the system that the program is done,
     which causes it to terminate the process.

     STATUS is the program's exit status, which becomes part of the
     process' termination 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 *Note Closing Streams::.  In addition, temporary files opened
     with the `tmpfile' function are removed; see *Note Temporary
     Files::.

  3. `_exit' is called, terminating the program.  *Note Termination
     Internals::.


File: libc.info,  Node: Exit Status,  Next: Cleanups on Exit,  Prev: Normal Termination,  Up: Program Termination

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.

   Don't confuse a program's exit status with a process' termination
status.  There are lots of ways a process can terminate besides having
it's program finish.  In the event that the process termination _is_
caused by program termination (i.e. `exit'), though, the program's exit
status becomes part of the process' termination status.


File: libc.info,  Node: Cleanups on Exit,  Next: Aborting a Program,  Prev: Exit Status,  Up: Program Termination

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.


File: libc.info,  Node: Aborting a Program,  Next: Termination Internals,  Prev: Cleanups on Exit,  Up: Program Termination

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 *Note 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.


File: libc.info,  Node: Termination Internals,  Prev: Aborting a Program,  Up: Program Termination

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

 - Function: void _Exit (int STATUS)
     The `_Exit' function is the ISO C equivalent to `_exit'.  The
     ISO C committee members were not sure whether the definitions of
     `_exit' and `_Exit' were compatible so they have not used the
     POSIX name.

     This function was introduced in ISO C99 and is declared in
     `stdlib.h'.

   When a process terminates for any reason--either because the program
terminates, or as a result of a signal--the following things happen:

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

   * A process exit status is saved to be reported back to the parent
     process via `wait' or `waitpid'; see *Note Process Completion::.
     If the program exited, this status includes as its low-order 8
     bits the program exit status.

   * 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.  *Note 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.  *Note Job Control::.


File: libc.info,  Node: Processes,  Next: Job Control,  Prev: Program Basics,  Up: Top

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.

* Menu:

* Running a Command::           The easy way to run another program.
* Process Creation Concepts::   An overview of the hard way to do it.
* Process Identification::      How to get the process ID of a process.
* Creating a Process::          How to fork a child process.
* Executing a File::            How to make a process execute another program.
* Process Completion::          How to tell when a child process has completed.
* Process Completion Status::   How to interpret the status value
                                 returned from a child process.
* BSD Wait Functions::  	More functions, for backward compatibility.
* Process Creation Example::    A complete example program.


File: libc.info,  Node: Running a Command,  Next: Process Creation Concepts,  Up: Processes

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.  *Note Process Completion::, for details on
     how this status code can be interpreted.

     If the COMMAND argument is a null pointer, a return value of zero
     indicates that no command processor is available.

     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
     `system' is called.  If the thread gets canceled these resources
     stay allocated until the program ends.  To avoid this calls to
     `system' should be protected using cancelation handlers.

     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 (*note 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.


File: libc.info,  Node: Process Creation Concepts,  Next: Process Identification,  Prev: Running a Command,  Up: Processes

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'
(*note 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 *Note 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.


File: libc.info,  Node: Process Identification,  Next: Creating a Process,  Prev: Process Creation Concepts,  Up: Processes

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.


File: libc.info,  Node: Creating a Process,  Next: Executing a File,  Prev: Process Identification,  Up: Processes

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; *note 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.  *Note Control
     Operations::.  However, the file position associated with each
     descriptor is shared by both processes; *note File Position::.

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

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

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

   * The set of pending signals (*note 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 some 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 `_exit' 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.


File: libc.info,  Node: Executing a File,  Next: Process Completion,  Prev: Creating a Process,  Up: Processes

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.

   To see the effects of `exec' from the point of view of the called
program, *Note Program Basics::.

   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.
     *Note 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 *Note
     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 *Note 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
     (*note 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.  *Note 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 (*note 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.  *Note 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.  *Note Process Creation
     Concepts::.

   * Session and process group membership.  *Note Concepts of Job
     Control::.

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

   * Pending alarms.  *Note Setting an Alarm::.

   * Current working directory and root directory.  *Note 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.  *Note Setting Permissions::.

   * Process signal mask; see *Note Process Signal Mask::.

   * Pending signals; see *Note Blocking Signals::.

   * Elapsed processor time associated with the process; see *Note
     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 *Note 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 *Note 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 *Note
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' (*note Descriptors and Streams::).


File: libc.info,  Node: Process Completion,  Next: Process Completion Status,  Prev: Executing a File,  Up: Processes

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.

     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
     `waitpid' is called.  If the thread gets canceled these resources
     stay allocated until the program ends.  To avoid this calls to
     `waitpid' should be protected using cancelation handlers.

     The return value is normally the process ID of the child process
     whose status is reported.  If there are child processes but none
     of them is waiting to be noticed, `waitpid' will block until one
     is.  However, if the `WNOHANG' option was specified, `waitpid'
     will return zero instead of blocking.

     If a specific PID to wait for was given to `waitpid', it will
     ignore all other children (if any).  Therefore if there are
     children waiting to be noticed but the child whose PID was
     specified is not one of them, `waitpid' will block or return zero
     as described above.

     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.  *Note 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)

     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
     `wait' is called.  If the thread gets canceled these resources
     stay allocated until the program ends.  To avoid this calls to
     `wait' should be protected using cancelation handlers.

 - 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).  *Note 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, status, serrno;
       serrno = errno;
       while (1)
         {
           pid = waitpid (WAIT_ANY, &status, WNOHANG);
           if (pid < 0)
             {
               perror ("waitpid");
               break;
             }
           if (pid == 0)
             break;
           notice_termination (pid, status);
         }
       errno = serrno;
     }


File: libc.info,  Node: Process Completion Status,  Next: BSD Wait Functions,  Prev: Process Completion,  Up: Processes

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

   If the exit status value (*note 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.  *Note
     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.  *Note 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.


File: libc.info,  Node: BSD Wait Functions,  Next: Process Creation Example,  Prev: Process Completion Status,  Up: Processes

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 that of the
          `WTERMSIG' macro.

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

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

    `int w_stopsig'
          The value of this member is the same as that 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).  *Note Resource Usage::.


File: libc.info,  Node: Process Creation Example,  Prev: BSD Wait Functions,  Up: Processes

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.  *Note Termination Internals::.


File: libc.info,  Node: Job Control,  Next: Name Service Switch,  Prev: Processes,  Up: Top

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
(*note Process Creation Concepts::) and signal handling (*note Signal
Handling::) in order to understand this material presented in this
chapter.

* Menu:

* Concepts of Job Control::     Jobs can be controlled by a shell.
* Job Control is Optional::     Not all POSIX systems support job control.
* Controlling Terminal::        How a process gets its controlling terminal.
* Access to the Terminal::      How processes share the controlling terminal.
* Orphaned Process Groups::     Jobs left after the user logs out.
* Implementing a Shell::        What a shell must do to implement job control.
* Functions for Job Control::   Functions to control process groups.

