aboutsummaryrefslogtreecommitdiff
path: root/manual/=process.texinfo
diff options
context:
space:
mode:
Diffstat (limited to 'manual/=process.texinfo')
-rw-r--r--manual/=process.texinfo1452
1 files changed, 1452 insertions, 0 deletions
diff --git a/manual/=process.texinfo b/manual/=process.texinfo
new file mode 100644
index 0000000000..63c723ed37
--- /dev/null
+++ b/manual/=process.texinfo
@@ -0,0 +1,1452 @@
+@node Processes, Job Control, Signal Handling, Top
+@chapter Processes
+
+@cindex process
+@dfn{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. Child processes are created by
+a parent process, and inherit many of their attributes from the parent
+process.
+
+This chapter describes how a program can create, terminate, and control
+child processes.
+
+@menu
+* Program Arguments:: Parsing the command-line arguments to
+ a program.
+* Environment Variables:: How to access parameters inherited from
+ a parent process.
+* Program Termination:: How to cause a process to terminate and
+ return status information to its parent.
+* Creating New Processes:: Running other programs.
+@end menu
+
+
+@node Program Arguments, Environment Variables, , Processes
+@section Program Arguments
+@cindex program arguments
+@cindex command line arguments
+
+@cindex @code{main} function
+When your C program starts, it begins by executing the function called
+@code{main}. You can define @code{main} either to take no arguments,
+or to take two arguments that represent the command line arguments
+to the program, like this:
+
+@example
+int main (int @var{argc}, char *@var{argv}[])
+@end example
+
+@cindex argc (program argument count)
+@cindex argv (program argument vector)
+The command line arguments are the whitespace-separated tokens typed by
+the user to the shell in invoking the program. The value of the
+@var{argc} argument is the number of command line arguments. The
+@var{argv} argument is a vector of pointers to @code{char}; sometimes it
+is also declared as @samp{char **@var{argv}}. The elements of
+@var{argv} are the individual command line argument strings. By
+convention, @code{@var{argv}[0]} is the file name of the program being
+run, and @code{@var{argv}[@var{argc}]} is a null pointer.
+
+If the syntax for the command line arguments to your program is simple
+enough, you can simply pick the arguments off from @var{argv} by hand.
+But unless your program takes a fixed number of arguments, or all of the
+arguments are interpreted in the same way (as file names, for example),
+you are usually better off using @code{getopt} to do the parsing.
+
+@menu
+* Argument Syntax Conventions:: By convention, program
+ options are specified by a
+ leading hyphen.
+* Parsing Program Arguments:: The @code{getopt} function.
+* Example Using getopt:: An example of @code{getopt}.
+@end menu
+
+@node Argument Syntax Conventions, Parsing Program Arguments, , Program Arguments
+@subsection Program Argument Syntax Conventions
+@cindex program argument syntax
+@cindex syntax, for program arguments
+@cindex command argument syntax
+
+The @code{getopt} function decodes options following the usual
+conventions for POSIX utilities:
+
+@itemize @bullet
+@item
+Arguments are options if they begin with a hyphen delimiter (@samp{-}).
+
+@item
+Multiple options may follow a hyphen delimiter in a single token if
+the options do not take arguments. Thus, @samp{-abc} is equivalent to
+@samp{-a -b -c}.
+
+@item
+Option names are single alphanumeric (as for @code{isalnum};
+see @ref{Classification of Characters}).
+
+@item
+Certain options require an argument. For example, the @samp{-o}
+command of the ld command requires an argument---an output file name.
+
+@item
+An option and its argument may or may appear as separate tokens. (In
+other words, the whitespace separating them is optional.) Thus,
+@samp{-o foo} and @samp{-ofoo} are equivalent.
+
+@item
+Options typically precede other non-option arguments.
+
+The implementation of @code{getopt} in the GNU C library normally makes
+it appear as if all the option arguments were specified before all the
+non-option arguments for the purposes of parsing, even if the user of
+your program intermixed option and non-option arguments. It does this
+by reordering the elements of the @var{argv} array. This behavior is
+nonstandard; if you want to suppress it, define the
+@code{_POSIX_OPTION_ORDER} environment variable. @xref{Standard
+Environment Variables}.
+
+@item
+The argument @samp{--} terminates all options; any following arguments
+are treated as non-option arguments, even if they begin with a hyphen.
+
+@item
+A token consisting of a single hyphen character is interpreted as an
+ordinary non-option argument. By convention, it is used to specify
+input from or output to the standard input and output streams.
+
+@item
+Options may be supplied in any order, or appear multiple times. The
+interpretation is left up to the particular application program.
+@end itemize
+
+@node Parsing Program Arguments, Example Using getopt, Argument Syntax Conventions, Program Arguments
+@subsection Parsing Program Arguments
+@cindex program arguments, parsing
+@cindex command arguments, parsing
+@cindex parsing program arguments
+
+Here are the details about how to call the @code{getopt} function. To
+use this facility, your program must include the header file
+@file{unistd.h}.
+@pindex unistd.h
+
+@comment unistd.h
+@comment POSIX.2
+@deftypevar int opterr
+If the value of this variable is nonzero, then @code{getopt} prints an
+error message to the standard error stream if it encounters an unknown
+option character or an option with a missing required argument. This is
+the default behavior. If you set this variable to zero, @code{getopt}
+does not print any messages, but it still returns @code{?} to indicate
+an error.
+@end deftypevar
+
+@comment unistd.h
+@comment POSIX.2
+@deftypevar int optopt
+When @code{getopt} encounters an unknown option character or an option
+with a missing required argument, it stores that option character in
+this variable. You can use this for providing your own diagnostic
+messages.
+@end deftypevar
+
+@comment unistd.h
+@comment POSIX.2
+@deftypevar int optind
+This variable is set by @code{getopt} to the index of the next element
+of the @var{argv} array to be processed. Once @code{getopt} has found
+all of the option arguments, you can use this variable to determine
+where the remaining non-option arguments begin. The initial value of
+this variable is @code{1}.
+@end deftypevar
+
+@comment unistd.h
+@comment POSIX.2
+@deftypevar {char *} optarg
+This variable is set by @code{getopt} to point at the value of the
+option argument, for those options that accept arguments.
+@end deftypevar
+
+@comment unistd.h
+@comment POSIX.2
+@deftypefun int getopt (int @var{argc}, char **@var{argv}, const char *@var{options})
+The @code{getopt} function gets the next option argument from the
+argument list specified by the @var{argv} and @var{argc} arguments.
+Normally these arguments' values come directly from the arguments of
+@code{main}.
+
+The @var{options} argument is a string that specifies the option
+characters that are valid for this program. An option character in this
+string can be followed by a colon (@samp{:}) to indicate that it takes a
+required argument.
+
+If the @var{options} argument string begins with a hyphen (@samp{-}), this
+is treated specially. It permits arguments without an option to be
+returned as if they were associated with option character @samp{\0}.
+
+The @code{getopt} function returns the option character for the next
+command line option. When no more option arguments are available, it
+returns @code{-1}. There may still be more non-option arguments; you
+must compare the external variable @code{optind} against the @var{argv}
+parameter to check this.
+
+If the options has an argument, @code{getopt} returns the argument by
+storing it in the varables @var{optarg}. You don't ordinarily need to
+copy the @code{optarg} string, since it is a pointer into the original
+@var{argv} array, not into a static area that might be overwritten.
+
+If @code{getopt} finds an option character in @var{argv} that was not
+included in @var{options}, or a missing option argument, it returns
+@samp{?} and sets the external variable @code{optopt} to the actual
+option character. In addition, if the external variable @code{opterr}
+is nonzero, @code{getopt} prints an error message.
+@end deftypefun
+
+@node Example Using getopt, , Parsing Program Arguments, Program Arguments
+@subsection Example of Parsing Program Arguments
+
+Here is an example showing how @code{getopt} is typically used. The
+key points to notice are:
+
+@itemize @bullet
+@item
+Normally, @code{getopt} is called in a loop. When @code{getopt} returns
+@code{-1}, indicating no more options are present, the loop terminates.
+
+@item
+A @code{switch} statement is used to dispatch on the return value from
+@code{getopt}. In typical use, each case just sets a variable that
+is used later in the program.
+
+@item
+A second loop is used to process the remaining non-option arguments.
+@end itemize
+
+@example
+@include testopt.c.texi
+@end example
+
+Here are some examples showing what this program prints with different
+combinations of arguments:
+
+@example
+% 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 -
+@end example
+
+@node Environment Variables, Program Termination, Program Arguments, Processes
+@section Environment Variables
+
+@cindex environment variable
+When a program is executed, it receives information about the context in
+which it was invoked in two ways. The first mechanism uses the
+@var{argv} and @var{argc} arguments to its @code{main} function, and is
+discussed in @ref{Program Arguments}. The second mechanism is
+uses @dfn{environment variables} and is discussed in this section.
+
+The @var{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 accessed.
+
+The environment variables discussed in this section are the same
+environment variables that you set using the assignments and the
+@code{export} command in the shell. Programs executed from the shell
+inherit all of the environment variables from the shell.
+
+@cindex environment
+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
+@dfn{environment}.
+
+Names of environment variables are case-sensitive and must not contain
+the character @samp{=}. 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.
+
+
+@menu
+* Environment Access:: How to get and set the values of
+ environment variables.
+* Standard Environment Variables:: These environment variables have
+ standard interpretations.
+@end menu
+
+@node Environment Access, Standard Environment Variables, , Environment Variables
+@subsection Environment Access
+@cindex environment access
+@cindex environment representation
+
+The value of an environment variable can be accessed with the
+@code{getenv} function. This is declared in the header file
+@file{stdlib.h}.
+@pindex stdlib.h
+
+@comment stdlib.h
+@comment ANSI
+@deftypefun {char *} getenv (const char *@var{name})
+This function returns a string that is the value of the environment
+variable @var{name}. You must not modify this string. In some systems
+not using the GNU library, it might be overwritten by subsequent calls
+to @code{getenv} (but not by any other library function). If the
+environment variable @var{name} is not defined, the value is a null
+pointer.
+@end deftypefun
+
+
+@comment stdlib.h
+@comment SVID
+@deftypefun int putenv (const char *@var{string})
+The @code{putenv} function adds or removes definitions from the environment.
+If the @var{string} is of the form @samp{@var{name}=@var{value}}, the
+definition is added to the environment. Otherwise, the @var{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.
+@end deftypefun
+
+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
+@ref{Executing a File}).
+
+@comment unistd.h
+@comment POSIX.1
+@deftypevar {char **} environ
+The environment is represented as an array of strings. Each string is
+of the format @samp{@var{name}=@var{value}}. The order in which
+strings appear in the environment is not significant, but the same
+@var{name} must not appear more than once. The last element of the
+array is a null pointer.
+
+This variable is not declared in any header file, but if you declare it
+in your own program as @code{extern}, the right thing will happen.
+
+If you just want to get the value of an environment variable, use
+@code{getenv}.
+@end deftypevar
+
+@node Standard Environment Variables, , Environment Access, Environment Variables
+@subsection Standard Environment Variables
+@cindex standard environment variables
+
+These environment variables have standard meanings.
+This doesn't mean that they are always present in the
+environment, though; it just means that if these variables @emph{are}
+present, they have these meanings, and that you shouldn't try to use
+these environment variable names for some other purpose.
+
+@table @code
+@item HOME
+@cindex HOME environment variable
+@cindex home directory
+This is a string representing the user's @dfn{home directory}, or
+initial default working directory. @xref{User Database}, for a
+more secure way of determining this information.
+
+@comment RMS says to explay why HOME is better, but I don't know why.
+
+@item LOGNAME
+@cindex LOGNAME environment variable
+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
+@code{getlogin} (@pxref{User Identification Functions}) is better for
+that purpose.
+
+@comment RMS says to explay why LOGNAME is better, but I don't know why.
+
+@item PATH
+@cindex PATH environment variable
+A @dfn{path} is a sequence of directory names which is used for
+searching for a file. The variable @var{PATH} holds a path The
+@code{execlp} and @code{execvp} functions (@pxref{Executing a File})
+uses 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. (@xref{Working Directory}.)
+
+A typical value for this environment variable might be a string like:
+
+@example
+.:/bin:/etc:/usr/bin:/usr/new/X11:/usr/new:/usr/local:/usr/local/bin
+@end example
+
+This means that if the user tries to execute a program named @code{foo},
+the system will look for files named @file{./foo}, @file{/bin/foo},
+@file{/etc/foo}, and so on. The first of these files that exists is
+the one that is executed.
+
+@item TERM
+@cindex TERM environment variable
+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
+(@pxref{Finding a Terminal Description,Find,,termcap,The Termcap Library
+Manual}) use the @code{TERM} environment variable, for example.
+
+@item TZ
+@cindex TZ environment variable
+This specifies the time zone. @xref{Time Zone}, for information about
+the format of this string and how it is used.
+
+@item LANG
+@cindex LANG environment variable
+This specifies the default locale to use for attribute categories where
+neither @code{LC_ALL} nor the specific environment variable for that
+category is set. @xref{Locales}, for more information about
+locales.
+
+@item LC_ALL
+@cindex LC_ALL environment variable
+This is similar to the @code{LANG} environment variable. However, its
+value takes precedence over any values provided for the individual
+attribute category environment variables, or for the @code{LANG}
+environment variable.
+
+@item LC_COLLATE
+@cindex LC_COLLATE environment variable
+This specifies what locale to use for string sorting.
+
+@item LC_CTYPE
+@cindex LC_CTYPE environment variable
+This specifies what locale to use for character sets and character
+classification.
+
+@item LC_MONETARY
+@cindex LC_MONETARY environment variable
+This specifies what locale to use for formatting monetary values.
+
+@item LC_NUMERIC
+@cindex LC_NUMERIC environment variable
+This specifies what locale to use for formatting numbers.
+
+@item LC_TIME
+@cindex LC_TIME environment variable
+This specifies what locale to use for formatting date/time values.
+
+@item _POSIX_OPTION_ORDER
+@cindex _POSIX_OPTION_ORDER environment variable.
+If this environment variable is defined, it suppresses the usual
+reordering of command line arguments by @code{getopt}. @xref{Program
+Argument Syntax Conventions}.
+@end table
+
+@node Program Termination, Creating New Processes, Environment Variables, Processes
+@section Program Termination
+@cindex program termination
+@cindex process termination
+
+@cindex exit status value
+The usual way for a program to terminate is simply for its @code{main}
+function to return. The @dfn{exit status value} returned from the
+@code{main} function is used to report information back to the process's
+parent process or shell.
+
+A program can also terminate normally calling the @code{exit}
+function
+
+In addition, programs can be terminated by signals; this is discussed in
+more detail in @ref{Signal Handling}. The @code{abort} function causes
+a terminal that kills the program.
+
+@menu
+* Normal Program Termination::
+* Exit Status:: Exit Status
+* Cleanups on Exit:: Cleanups on Exit
+* Aborting a Program::
+* Termination Internals:: Termination Internals
+@end menu
+
+@node Normal Program Termination, Exit Status, , Program Termination
+@subsection Normal Program Termination
+
+@comment stdlib.h
+@comment ANSI
+@deftypefun void exit (int @var{status})
+The @code{exit} function causes normal program termination with status
+@var{status}. This function does not return.
+@end deftypefun
+
+When a program terminates normally by returning from its @code{main}
+function or by calling @code{exit}, the following actions occur in
+sequence:
+
+@enumerate
+@item
+Functions that were registered with the @code{atexit} or @code{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 unlock locks
+in shared data bases.
+
+@item
+All open streams are closed; writing out any buffered output data. See
+@ref{Opening and Closing Streams}. In addition, temporary files opened
+with the @code{tmpfile} function are removed; see @ref{Temporary Files}.
+
+@item
+@code{_exit} is called. @xref{Termination Internals}
+@end enumerate
+
+@node Exit Status, Cleanups on Exit, Normal Program Termination, Program Termination
+@subsection Exit Status
+@cindex 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
+@dfn{exit status}. This is a value between 0 and 255 that the exiting
+process passes as an argument to @code{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.
+
+@strong{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 @code{errno}
+as the exit status---these can exceed 255.
+
+@strong{Portability note:} Some non-POSIX systems use different
+conventions for exit status values. For greater portability, you can
+use the macros @code{EXIT_SUCCESS} and @code{EXIT_FAILURE} for the
+conventional status value for success and failure, respectively. They
+are declared in the file @file{stdlib.h}.
+@pindex stdlib.h
+
+@comment stdlib.h
+@comment ANSI
+@deftypevr Macro int EXIT_SUCCESS
+This macro can be used with the @code{exit} function to indicate
+successful program completion.
+
+On POSIX systems, the value of this macro is @code{0}. On other
+systems, the value might be some other (possibly non-constant) integer
+expression.
+@end deftypevr
+
+@comment stdlib.h
+@comment ANSI
+@deftypevr Macro int EXIT_FAILURE
+This macro can be used with the @code{exit} function to indicate
+unsuccessful program completion in a general sense.
+
+On POSIX systems, the value of this macro is @code{1}. On other
+systems, the value might be some other (possibly non-constant) integer
+expression. Other nonzero status values also indicate future. Certain
+programs use different nonzero status values to indicate particular
+kinds of "non-success". For example, @code{diff} uses status value
+@code{1} to mean that the files are different, and @code{2} or more to
+mean that there was difficulty in opening the files.
+@end deftypevr
+
+@node Cleanups on Exit, Aborting a Program, Exit Status, Program Termination
+@subsection Cleanups on Exit
+
+@comment stdlib.h
+@comment ANSI
+@deftypefun int atexit (void (*@var{function}))
+The @code{atexit} function registers the function @var{function} to be
+called at normal program termination. The @var{function} is called with
+no arguments.
+
+The return value from @code{atexit} is zero on success and nonzero if
+the function cannot be registered.
+@end deftypefun
+
+@comment stdlib.h
+@comment GNU
+@deftypefun int on_exit (void (*@var{function})(int @var{status}, void *@var{arg}), void *@var{arg})
+This function is a somewhat more powerful variant of @code{atexit}. It
+accepts two arguments, a function @var{function} and an arbitrary
+pointer @var{arg}. At normal program termination, the @var{function} is
+called with two arguments: the @var{status} value passed to @code{exit},
+and the @var{arg}.
+
+This function is a GNU extension, and may not be supported by other
+implementations.
+@end deftypefun
+
+Here's a trivial program that illustrates the use of @code{exit} and
+@code{atexit}:
+
+@example
+#include <stdio.h>
+#include <stdlib.h>
+
+void bye (void)
+@{
+ printf ("Goodbye, cruel world....\n");
+@}
+
+void main (void)
+@{
+ atexit (bye);
+ exit (EXIT_SUCCESS);
+@}
+@end example
+
+@noindent
+When this program is executed, it just prints the message and exits.
+
+
+@node Aborting a Program, Termination Internals, Cleanups on Exit, Program Termination
+@subsection Aborting a Program
+@cindex aborting a program
+
+You can abort your program using the @code{abort} function. The prototype
+for this function is in @file{stdlib.h}.
+@pindex stdlib.h
+
+@comment stdlib.h
+@comment ANSI
+@deftypefun void abort ()
+The @code{abort} function causes abnormal program termination, without
+executing functions registered with @code{atexit} or @code{on_exit}.
+
+This function actually terminates the process by raising a
+@code{SIGABRT} signal, and your program can include a handler to
+intercept this signal; see @ref{Signal Handling}.
+
+@strong{Incomplete:} Why would you want to define such a handler?
+@end deftypefun
+
+@node Termination Internals, , Aborting a Program, Program Termination
+@subsection Termination Internals
+
+The @code{_exit} function is the primitive used for process termination
+by @code{exit}. It is declared in the header file @file{unistd.h}.
+@pindex unistd.h
+
+@comment unistd.h
+@comment POSIX.1
+@deftypefun void _exit (int @var{status})
+The @code{_exit} function is the primitive for causing a process to
+terminate with status @var{status}. Calling this function does not
+execute cleanup functions registered with @code{atexit} or
+@code{on_exit}.
+@end deftypefun
+
+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:
+
+@itemize @bullet
+@item
+All open file descriptors in the process are closed. @xref{Low-Level
+Input/Output}.
+
+@item
+The low-order 8 bits of the return status code are saved to be reported
+back to the parent process via @code{wait} or @code{waitpid}; see
+@ref{Process Completion}.
+
+@item
+Any child processes of the process being terminated are assigned a new
+parent process. (This is the @code{init} process, with process ID 1.)
+
+@item
+A @code{SIGCHLD} signal is sent to the parent process.
+
+@item
+If the process is a session leader that has a controlling terminal, then
+a @code{SIGHUP} signal is sent to each process in the foreground job,
+and the controlling terminal is disassociated from that session.
+@xref{Job Control}.
+
+@item
+If termination of a process causes a process group to become orphaned,
+and any member of that process group is stopped, then a @code{SIGHUP}
+signal and a @code{SIGCONT} signal are sent to each process in the
+group. @xref{Job Control}.
+@end itemize
+
+@node Creating New Processes, , Program Termination, Processes
+@section Creating New Processes
+
+This section describes how your program can cause other programs to be
+executed. 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 @code{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 get a process to 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.
+@end menu
+
+
+@node Running a Command, Process Creation Concepts, , Creating New Processes
+@subsection Running a Command
+@cindex running a command
+
+The easy way to run another program is to use the @code{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.
+
+@pindex stdlib.h
+
+@comment stdlib.h
+@comment ANSI
+@deftypefun int system (const char *@var{command})
+This function executes @var{command} as a shell command. In the GNU C
+library, it always uses the default shell @code{sh} to run the command.
+In particular, it searching the directories in @code{PATH} to find
+programs to execute. The return value is @code{-1} if it wasn't
+possible to create the shell process, and otherwise is the status of the
+shell process. @xref{Process Completion}, for details on how this
+status code can be interpreted.
+@pindex sh
+@end deftypefun
+
+The @code{system} function is declared in the header file
+@file{stdlib.h}.
+
+@strong{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 @code{system
+(o)}; in this case the return value is nonzero if and only if such a
+processor is available.
+
+The @code{popen} and @code{pclose} functions (@pxref{Pipe to a
+Subprocess}) are closely related to the @code{system} function. They
+allow the parent process to communicate with the standard input and
+output channels of the command being executed.
+
+@node Process Creation Concepts, Process Identification, Running a Command, Creating New Processes
+@subsection 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.
+
+@cindex process ID
+@cindex process lifetime
+Each process is named by a @dfn{process ID} number. A unique process ID
+is allocated to each process when it is created. The @dfn{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.
+
+@cindex creating a process
+@cindex forking a process
+@cindex child process
+@cindex parent process
+Processes are created with the @code{fork} system call (so the operation
+of creating a new process is sometimes called @dfn{forking} a process).
+The @dfn{child process} created by @code{fork} is an exact clone of the
+original @dfn{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. This is done with the @code{wait}
+or @code{waitpid} functions (@pxref{Process Completion}). These
+functions give the parent 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 @code{fork} call returns.
+You can use the return value from @code{fork} to tell whether the program
+is running in the parent process or the child.
+
+@cindex process image
+Having all processes run the same program is usually not very useful.
+But the child can execute another program using one of the @code{exec}
+functions; see @ref{Executing a File}. The program that the process is
+executing is called its @dfn{process image}. Starting execution of a
+new program causes the process to forget all about its current process
+image; when the new program exits, the process exits too, instead of
+returning to the previous process image.
+
+
+@node Process Identification, Creating a Process, Process Creation Concepts, Creating New Processes
+@subsection Process Identification
+
+The @code{pid_t} data type represents process IDs. You can get the
+process ID of a process by calling @code{getpid}. The function
+@code{getppid} returns the process ID of the parent of the parent of the
+current process (this is also known as the @dfn{parent process ID}).
+Your program should include the header files @file{unistd.h} and
+@file{sys/types.h} to use these functions.
+@pindex sys/types.h
+@pindex unistd.h
+
+@comment sys/types.h
+@comment POSIX.1
+@deftp {Data Type} pid_t
+The @code{pid_t} data type is a signed integer type which is capable
+of representing a process ID. In the GNU library, this is an @code{int}.
+@end deftp
+
+@comment unistd.h
+@comment POSIX.1
+@deftypefun pid_t getpid ()
+The @code{getpid} function returns the process ID of the current process.
+@end deftypefun
+
+@comment unistd.h
+@comment POSIX.1
+@deftypefun pid_t getppid ()
+The @code{getppid} function returns the process ID of the parent of the
+current process.
+@end deftypefun
+
+@node Creating a Process, Executing a File, Process Identification, Creating New Processes
+@subsection Creating a Process
+
+The @code{fork} function is the primitive for creating a process.
+It is declared in the header file @file{unistd.h}.
+@pindex unistd.h
+
+@comment unistd.h
+@comment POSIX.1
+@deftypefun pid_t fork ()
+The @code{fork} function creates a new process.
+
+If the operation is successful, there are then both parent and child
+processes and both see @code{fork} return, but with different values: it
+returns a value of @code{0} in the child process and returns the child's
+process ID in the parent process. If the child process could not be
+created, a value of @code{-1} is returned in the parent process. The
+following @code{errno} error conditions are defined for this function:
+
+@table @code
+@item EAGAIN
+There aren't enough system resources to create another process, or the
+user already has too many processes running.
+
+@item ENOMEM
+The process requires more space than the system can supply.
+@end table
+@end deftypefun
+
+The specific attributes of the child process that differ from the
+parent process are:
+
+@itemize @bullet
+@item
+The child process has its own unique process ID.
+
+@item
+The parent process ID of the child process is the process ID of its
+parent process.
+
+@item
+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. @xref{Control Operations}.
+
+@item
+The elapsed processor times for the child process are set to zero;
+see @ref{Processor Time}.
+
+@item
+The child doesn't inherit file locks set by the parent process.
+@xref{Control Operations}.
+
+@item
+The child doesn't inherit alarms set by the parent process.
+@xref{Setting an Alarm}.
+
+@item
+The set of pending signals (@pxref{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.)
+@end itemize
+
+
+@comment unistd.h
+@comment BSD
+@deftypefun pid_t vfork (void)
+The @code{vfork} function is similar to @code{fork} but more efficient;
+however, there are restrictions you must follow to use it safely.
+
+While @code{fork} makes a complete copy of the calling process's address
+space and allows both the parent and child to execute independently,
+@code{vfork} does not make this copy. Instead, the child process
+created with @code{vfork} shares its parent's address space until it calls
+one of the @code{exec} functions. In the meantime, the parent process
+suspends execution.
+
+You must be very careful not to allow the child process created with
+@code{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 @code{vfork}! This
+would leave the parent process's control information very confused. If
+in doubt, use @code{fork} instead.
+
+Some operating systems don't really implement @code{vfork}. The GNU C
+library permits you to use @code{vfork} on all systems, but actually
+executes @code{fork} if @code{vfork} isn't available.
+@end deftypefun
+
+@node Executing a File, Process Completion, Creating a Process, Creating New Processes
+@subsection Executing a File
+@cindex executing a file
+@cindex @code{exec} functions
+
+This section describes the @code{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 @file{unistd.h}.
+@pindex unistd.h
+
+@comment unistd.h
+@comment POSIX.1
+@deftypefun int execv (const char *@var{filename}, char *const @var{argv}@t{[]})
+The @code{execv} function executes the file named by @var{filename} as a
+new process image.
+
+The @var{argv} argument is an array of null-terminated strings that is
+used to provide a value for the @code{argv} argument to the @code{main}
+function of the program to be executed. The last element of this array
+must be a null pointer. @xref{Program Arguments}, for information on
+how programs can access these arguments.
+
+The environment for the new process image is taken from the
+@code{environ} variable of the current process image; see @ref{Environment
+Variables}, for information about environments.
+@end deftypefun
+
+@comment unistd.h
+@comment POSIX.1
+@deftypefun int execl (const char *@var{filename}, const char *@var{arg0}, @dots{})
+This is similar to @code{execv}, but the @var{argv} strings are
+specified individually instead of as an array. A null pointer must be
+passed as the last such argument.
+@end deftypefun
+
+@comment unistd.h
+@comment POSIX.1
+@deftypefun int execve (const char *@var{filename}, char *const @var{argv}@t{[]}, char *const @var{env}@t{[]})
+This is similar to @code{execv}, but permits you to specify the environment
+for the new program explicitly as the @var{env} argument. This should
+be an array of strings in the same format as for the @code{environ}
+variable; see @ref{Environment Access}.
+@end deftypefun
+
+@comment unistd.h
+@comment POSIX.1
+@deftypefun int execle (const char *@var{filename}, const char *@var{arg0}, char *const @var{env}@t{[]}, @dots{})
+This is similar to @code{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 @var{argv}
+argument, and should be an array of strings in the same format as for
+the @code{environ} variable.
+@end deftypefun
+
+@comment unistd.h
+@comment POSIX.1
+@deftypefun int execvp (const char *@var{filename}, char *const @var{argv}@t{[]})
+The @code{execvp} function is similar to @code{execv}, except that it
+searches the directories listed in the @code{PATH} environment variable
+(@pxref{Standard Environment Variables}) to find the full file name of a
+file from @var{filename} if @var{filename} does not contain a slash.
+
+This function is useful for executing installed system utility programs,
+so that the user can control where to look for them. It is also useful
+in shells, for executing commands typed by the user.
+@end deftypefun
+
+@comment unistd.h
+@comment POSIX.1
+@deftypefun int execlp (const char *@var{filename}, const char *@var{arg0}, @dots{})
+This function is like @code{execl}, except that it performs the same
+file name searching as the @code{execvp} function.
+@end deftypefun
+
+
+The size of the argument list and environment list taken together must not
+be greater than @code{ARG_MAX} bytes. @xref{System Parameters}.
+
+@strong{Incomplete:} The POSIX.1 standard requires some statement here
+about how null terminators, null pointers, and alignment requirements
+affect the total size of the argument and environment lists.
+
+These functions normally don't return, since execution of a new program
+causes the currently executing program to go away completely. A value
+of @code{-1} is returned in the event of a failure. In addition to the
+usual file name syntax errors (@pxref{File Name Errors}), the following
+@code{errno} error conditions are defined for these functions:
+
+@table @code
+@item E2BIG
+The combined size of the new program's argument list and environment list
+is larger than @code{ARG_MAX} bytes.
+
+@item ENOEXEC
+The specified file can't be executed because it isn't in the right format.
+
+@item ENOMEM
+Executing the specified file requires more storage than is available.
+@end table
+
+If execution of the new file is successful, the access time field of the
+file is updated as if the file had been opened. @xref{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,
+except for the arguments and the environment, but many other attributes
+of the process are unchanged:
+
+@itemize @bullet
+@item
+The process ID and the parent process ID. @xref{Process Creation Concepts}.
+
+@item
+Session and process group membership. @xref{Job Control Concepts}.
+
+@item
+Real user ID and group ID, and supplementary group IDs. @xref{User/Group
+IDs of a Process}.
+
+@item
+Pending alarms. @xref{Setting an Alarm}.
+
+@item
+Current working directory and root directory. @xref{Working Directory}.
+
+@item
+File mode creation mask. @xref{Setting Permissions}.
+
+@item
+Process signal mask; see @ref{Process Signal Mask}.
+
+@item
+Pending signals; see @ref{Blocking Signals}.
+
+@item
+Elapsed processor time associated with the process; see @ref{Processor Time}.
+@end itemize
+
+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 @ref{User/Group IDs of a Process}.
+
+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 @ref{Signal Handling}.
+
+File descriptors open in the existing process image remain open in the
+new process image, unless they have the @code{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 @ref{Low-Level
+Input/Output}.
+
+Streams, by contrast, cannot survive through @code{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-@code{exec} process image has a descriptor inside
+it, and these descriptors do survive through @code{exec} (provided that
+they do not have @code{FD_CLOEXEC} set. The new process image can
+reconnect these to new streams using @code{fdopen}.
+
+@node Process Completion, Process Completion Status, Executing a File, Creating New Processes
+@subsection Process Completion
+@cindex process completion
+@cindex waiting for completion of child process
+@cindex testing exit status of child process
+
+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 @file{sys/wait.h}.
+@pindex sys/wait.h
+
+@comment sys/wait.h
+@comment POSIX.1
+@deftypefun pid_t waitpid (pid_t @var{pid}, int *@var{status_ptr}, int @var{options})
+The @code{waitpid} function is used to request status information from a
+child process whose process ID is @var{pid}. Normally, the calling
+process is suspended until the child process makes status information
+available by terminating.
+
+Other values for the @var{pid} argument have special interpretations. A
+value of @code{-1} or @code{WAIT_ANY} requests status information for
+any child process; a value of @code{0} or @code{WAIT_MYPGRP} requests
+information for any child process in the same process group as the
+calling process; and any other negative value @minus{} @var{pgid}
+requests information for any child process whose process group ID is
+@var{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 programs, you need to call @code{waitpid} again.
+
+The @var{options} argument is a bit mask. Its value should be the
+bitwise OR (that is, the @samp{|} operator) of zero or more of the
+@code{WNOHANG} and @code{WUNTRACED} flags. You can use the
+@code{WNOHANG} flag to indicate that the parent process shouldn't wait;
+and the @code{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 @var{status_ptr} points to, unless @var{status_ptr} is a null pointer.
+
+The return value is normally the process ID of the child process whose
+status is reported. If the @code{WNOHANG} option was specified and no
+child process is waiting to be noticed, a value of zero is returned. A
+value of @code{-1} is returned in case of error. The following
+@code{errno} error conditions are defined for this function:
+
+@table @code
+@item EINTR
+The function was interrupted by delivery of a signal to the calling
+process.
+
+@item ECHILD
+There are no child processes to wait for, or the specified @var{pid}
+is not a child of the calling process.
+
+@item EINVAL
+An invalid value was provided for the @var{options} argument.
+@end table
+@end deftypefun
+
+These symbolic constants are defined as values for the @var{pid} argument
+to the @code{waitpid} function.
+
+@table @code
+@item WAIT_ANY
+This constant macro (whose value is @code{-1}) specifies that
+@code{waitpid} should return status information about any child process.
+
+@item WAIT_MYPGRP
+This constant (with value @code{0}) specifies that @code{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 @var{options}
+argument to the @code{waitpid} function. You can bitwise-OR the flags
+together to obtain a value to use as the argument.
+
+@item WNOHANG
+This flag specifies that @code{waitpid} should return immediately
+instead of waiting if there is no child process ready to be noticed.
+
+@item WUNTRACED
+This macro is used to specify that @code{waitpid} should also report the
+status of any child processes that have been stopped as well as those
+that have terminated.
+@end table
+
+@deftypefun pid_t wait (int *@var{status_ptr})
+This is a simplified version of @code{waitpid}, and is used to wait
+until any one child process terminates.
+
+@example
+wait (&status)
+@end example
+
+@noindent
+is equivalent to:
+
+@example
+waitpid (-1, &status, 0)
+@end example
+
+Here's an example of how to use @code{waitpid} to get the status from
+all child processes that have terminated, without ever waiting. This
+function is designed to be used as a handler for @code{SIGCHLD}, the
+signal that indicates that at least one child process has terminated.
+
+@example
+void
+sigchld_handler (int signum)
+@{
+ int pid;
+ int status;
+ while (1) @{
+ pid = waitpid (WAIT_ANY, Estatus, WNOHANG);
+ if (pid < 0) @{
+ perror ("waitpid");
+ break;
+ @}
+ if (pid == 0)
+ break;
+ notice_termination (pid, status);
+ @}
+@}
+@end example
+@end deftypefun
+
+@node Process Completion Status, BSD wait Functions, Process Completion, Creating New Processes
+@subsection Process Completion Status
+
+If the exit status value (@pxref{Program Termination}) of the child
+process is zero, then the status value reported by @code{waitpid} or
+@code{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 @file{sys/wait.h}.
+@pindex sys/wait.h
+
+@comment sys/wait.h
+@comment POSIX.1
+@deftypefn Macro int WIFEXITED (int @var{status})
+This macro returns a non-zero value if the child process terminated
+normally with @code{exit} or @code{_exit}.
+@end deftypefn
+
+@comment sys/wait.h
+@comment POSIX.1
+@deftypefn Macro int WEXITSTATUS (int @var{status})
+If @code{WIFEXITED} is true of @var{status}, this macro returns the
+low-order 8 bits of the exit status value from the child process.
+@end deftypefn
+
+@comment sys/wait.h
+@comment POSIX.1
+@deftypefn Macro int WIFSIGNALED (int @var{status})
+This macro returns a non-zero value if the child process terminated
+by receiving a signal that was not handled.
+@end deftypefn
+
+@comment sys/wait.h
+@comment POSIX.1
+@deftypefn Macro int WTERMSIG (int @var{status})
+If @code{WIFSIGNALED} is true of @var{status}, this macro returns the
+number of the signal that terminated the child process.
+@end deftypefn
+
+@comment sys/wait.h
+@comment BSD
+@deftypefn Macro int WCOREDUMP (int @var{status})
+This macro returns a non-zero value if the child process terminated
+and produced a core dump.
+@end deftypefn
+
+@comment sys/wait.h
+@comment POSIX.1
+@deftypefn Macro int WIFSTOPPED (int @var{status})
+This macro returns a non-zero value if the child process is stopped.
+@end deftypefn
+
+@comment sys/wait.h
+@comment POSIX.1
+@deftypefn Macro int WSTOPSIG (int @var{status})
+If @code{WIFSTOPPED} is true of @var{status}, this macro returns the
+number of the signal that caused the child process to stop.
+@end deftypefn
+
+
+@node BSD wait Functions, Process Creation Example, Process Completion Status, Creating New Processes
+@subsection BSD Process Completion Functions
+
+The GNU library also provides these related facilities for compatibility
+with BSD Unix. BSD uses the @code{union wait} data type to represent
+status values rather than an @code{int}. The two representations are
+actually interchangeable; they describe the same bit patterns. The macros
+such as @code{WEXITSTATUS} are defined so that they will work on either
+kind of object, and the @code{wait} function is defined to accept either
+type of pointer as its @var{status_ptr} argument.
+
+These functions are declared in @file{sys/wait.h}.
+@pindex sys/wait.h
+
+@comment sys/wait.h
+@comment BSD
+@deftp {union Type} wait
+This data type represents program termination status values. It has
+the following members:
+
+@table @code
+@item int w_termsig
+This member is equivalent to the @code{WTERMSIG} macro.
+
+@item int w_coredump
+This member is equivalent to the @code{WCOREDUMP} macro.
+
+@item int w_retcode
+This member is equivalent to the @code{WEXISTATUS} macro.
+
+@item int w_stopsig
+This member is equivalent to the @code{WSTOPSIG} macro.
+@end table
+
+Instead of accessing these members directly, you should use the
+equivalent macros.
+@end deftp
+
+@comment sys/wait.h
+@comment BSD
+@deftypefun pid_t wait3 (union wait *@var{status_ptr}, int @var{options}, void * @var{usage})
+If @var{usage} is a null pointer, this function is equivalent to
+@code{waitpid (-1, @var{status_ptr}, @var{options})}.
+
+The @var{usage} argument may also be a pointer to a
+@code{struct rusage} object. Information about system resources used by
+terminated processes (but not stopped processes) is returned in this
+structure.
+
+@strong{Incomplete:} The description of the @code{struct rusage} structure
+hasn't been written yet. Put in a cross-reference here.
+@end deftypefun
+
+@comment sys/wait.h
+@comment BSD
+@deftypefun pid_t wait4 (pid_t @var{pid}, union wait *@var{status_ptr}, int @var{options}, void *@var{usage})
+If @var{usage} is a null pointer, this function is equivalent to
+@code{waitpid (@var{pid}, @var{status_ptr}, @var{options})}.
+
+The @var{usage} argument may also be a pointer to a
+@code{struct rusage} object. Information about system resources used by
+terminated processes (but not stopped processes) is returned in this
+structure.
+
+@strong{Incomplete:} The description of the @code{struct rusage} structure
+hasn't been written yet. Put in a cross-reference here.
+@end deftypefun
+
+@node Process Creation Example, , BSD wait Functions, Creating New Processes
+@subsection Process Creation Example
+
+Here is an example program showing how you might write a function
+similar to the built-in @code{system}. It executes its @var{command}
+argument using the equivalent of @samp{sh -c @var{command}}.
+
+@example
+#include <stddef.h>
+#include <stdlib.h>
+#include <unistd.h>
+#include <sys/types.h>
+#include <sys/wait.h>
+
+/* @r{Execute the command using this shell program.} */
+#define SHELL "/bin/sh"
+
+int
+my_system (char *command)
+@{
+ int status;
+ pid_t pid;
+
+ pid = fork ();
+ if (pid == 0) @{
+ /* @r{This is the child process. Execute the shell command.} */
+ execl (SHELL, SHELL, "-c", command, NULL);
+ exit (EXIT_FAILURE);
+ @}
+ else if (pid < 0)
+ /* @r{The fork failed. Report failure.} */
+ status = -1;
+ else @{
+ /* @r{This is the parent process. Wait for the child to complete.} */
+ if (waitpid (pid, &status, 0) != pid)
+ status = -1;
+ @}
+ return status;
+@}
+@end example
+
+@comment Yes, this example has been tested.
+
+There are a couple of things you should pay attention to in this
+example.
+
+Remember that the first @code{argv} argument supplied to the program
+represents the name of the program being executed. That is why, in the
+call to @code{execl}, @code{SHELL} is supplied once to name the program
+to execute and a second time to supply a value for @code{argv[0]}.
+
+The @code{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 @code{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. To do this, @code{exit} is called with a failure status.