<P>
This section describes the <CODE>exec</CODE> 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.
<A NAME="IDX1704"></A>
<P>
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 <TT>`unistd.h'</TT>.
<P>
<A NAME="IDX1705"></A>
<U>Function:</U> int <B>execv</B> <I>(const char *<VAR>filename</VAR>, char *const <VAR>argv</VAR><TT>[]</TT>)</I><P>
The <CODE>execv</CODE> function executes the file named by <VAR>filename</VAR> as a
new process image.
<P>
The <VAR>argv</VAR> argument is an array of null-terminated strings that is
used to provide a value for the <CODE>argv</CODE> argument to the <CODE>main</CODE>
function of the program to be executed.  The last element of this array
must be a null pointer.  See section <A HREF="library_22.html#SEC386" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_22.html#SEC386">Program Arguments</A>, for information on
how programs can access these arguments.
<P>
The environment for the new process image is taken from the
<CODE>environ</CODE> variable of the current process image; see section <A HREF="library_22.html#SEC392" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_22.html#SEC392">Environment Variables</A>, for information about environments.
<P>
<A NAME="IDX1706"></A>
<U>Function:</U> int <B>execl</B> <I>(const char *<VAR>filename</VAR>, const char *<VAR>arg0</VAR>, ...)</I><P>
This is similar to <CODE>execv</CODE>, but the <VAR>argv</VAR> strings are
specified individually instead of as an array.  A null pointer must be
passed as the last such argument.
<P>
<A NAME="IDX1707"></A>
<U>Function:</U> int <B>execve</B> <I>(const char *<VAR>filename</VAR>, char *const <VAR>argv</VAR><TT>[]</TT>, char *const <VAR>env</VAR><TT>[]</TT>)</I><P>
This is similar to <CODE>execv</CODE>, but permits you to specify the environment
for the new program explicitly as the <VAR>env</VAR> argument.  This should
be an array of strings in the same format as for the <CODE>environ</CODE> 
variable; see section <A HREF="library_22.html#SEC393" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_22.html#SEC393">Environment Access</A>.
<P>
<A NAME="IDX1708"></A>
<U>Function:</U> int <B>execle</B> <I>(const char *<VAR>filename</VAR>, const char *<VAR>arg0</VAR>, char *const <VAR>env</VAR><TT>[]</TT>, ...)</I><P>
This is similar to <CODE>execl</CODE>, 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</VAR>
argument, and should be an array of strings in the same format as for
the <CODE>environ</CODE> variable.
<P>
<A NAME="IDX1709"></A>
<U>Function:</U> int <B>execvp</B> <I>(const char *<VAR>filename</VAR>, char *const <VAR>argv</VAR><TT>[]</TT>)</I><P>
The <CODE>execvp</CODE> function is similar to <CODE>execv</CODE>, except that it
searches the directories listed in the <CODE>PATH</CODE> environment variable
(see section <A HREF="library_22.html#SEC394" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_22.html#SEC394">Standard Environment Variables</A>) to find the full file name of a
file from <VAR>filename</VAR> if <VAR>filename</VAR> does not contain a slash.
<P>
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.
<P>
<A NAME="IDX1710"></A>
<U>Function:</U> int <B>execlp</B> <I>(const char *<VAR>filename</VAR>, const char *<VAR>arg0</VAR>, ...)</I><P>
This function is like <CODE>execl</CODE>, except that it performs the same
file name searching as the <CODE>execvp</CODE> function.
<P>
The size of the argument list and environment list taken together must
not be greater than <CODE>ARG_MAX</CODE> bytes.  See section <A HREF="library_27.html#SEC455" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_27.html#SEC455">General Capacity Limits</A>.  In
the GNU system, the size (which compares against <CODE>ARG_MAX</CODE>)
includes, for each string, the number of characters in the string, plus
the size of a <CODE>char *</CODE>, plus one, rounded up to a multiple of the
size of a <CODE>char *</CODE>.  Other systems may have somewhat different
rules for counting.
<P>
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</CODE> is returned in the event of a failure.  In addition to the
usual file name syntax errors (see section <A HREF="library_10.html#SEC115" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_10.html#SEC115">File Name Errors</A>), the following
<CODE>errno</CODE> error conditions are defined for these functions:
<P>
<DL COMPACT>
<DT><CODE>E2BIG</CODE>
<DD>The combined size of the new program's argument list and environment
list is larger than <CODE>ARG_MAX</CODE> bytes.  The GNU system has no
specific limit on the argument list size, so this error code cannot
result, but you may get <CODE>ENOMEM</CODE> instead if the arguments are too
big for available memory.
<P>
<DT><CODE>ENOEXEC</CODE>
<DD>The specified file can't be executed because it isn't in the right format.
<P>
<DT><CODE>ENOMEM</CODE>
<DD>Executing the specified file requires more storage than is available.
</DL>
<P>
If execution of the new file succeeds, it updates the access time field
of the file as if the file had been read.  See section <A HREF="library_13.html#SEC209" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_13.html#SEC209">File Times</A>, for more
details about access times of files.
<P>
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.
<P>
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:
<P>
<UL>
<LI>
The process ID and the parent process ID.  See section <A HREF="library_23.html#SEC403" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_23.html#SEC403">Process Creation Concepts</A>.
<P>
<LI>
Session and process group membership.  See section <A HREF="library_24.html#SEC412" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_24.html#SEC412">Concepts of Job Control</A>.
<P>
<LI>
Real user ID and group ID, and supplementary group IDs.  See section <A HREF="library_25.html#SEC431" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_25.html#SEC431">The Persona of a Process</A>.
<P>
<LI>
Pending alarms.  See section <A HREF="library_19.html#SEC321" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_19.html#SEC321">Setting an Alarm</A>.
<P>
<LI>
Current working directory and root directory.  See section <A HREF="library_13.html#SEC188" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_13.html#SEC188">Working Directory</A>.
<P>
<LI>
File mode creation mask.  See section <A HREF="library_13.html#SEC207" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_13.html#SEC207">Assigning File Permissions</A>.
<P>
<LI>
Process signal mask; see section <A HREF="library_21.html#SEC371" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_21.html#SEC371">Process Signal Mask</A>.
<P>
<LI>
Pending signals; see section <A HREF="library_21.html#SEC368" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_21.html#SEC368">Blocking Signals</A>.
<P>
<LI>
Elapsed processor time associated with the process; see section <A HREF="library_19.html#SEC310" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_19.html#SEC310">Processor Time</A>.
</UL>
<P>
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 section <A HREF="library_25.html#SEC431" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_25.html#SEC431">The Persona of a Process</A>.
<P>
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 section <A HREF="library_21.html#SEC330" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_21.html#SEC330">Signal Handling</A>.
<P>
File descriptors open in the existing process image remain open in the
new process image, unless they have the <CODE>FD_CLOEXEC</CODE>
(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 section <A HREF="library_12.html#SEC171" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_12.html#SEC171">Low-Level Input/Output</A>.
<P>
Streams, by contrast, cannot survive through <CODE>exec</CODE> 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</CODE> process image has a descriptor inside
it, and these descriptors do survive through <CODE>exec</CODE> (provided that
they do not have <CODE>FD_CLOEXEC</CODE> set.  The new process image can
reconnect these to new streams using <CODE>fdopen</CODE> (see section <A HREF="library_12.html#SEC175" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_12.html#SEC175">Descriptors and Streams</A>).
<P>
<A NAME="IDX1711"></A>
<A NAME="IDX1712"></A>
<A NAME="IDX1713"></A>
<H2><A NAME="SEC407" HREF="library_toc.html#SEC407" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC407">Process Completion</A></H2>
<P>
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 <TT>`sys/wait.h'</TT>.
<A NAME="IDX1714"></A>
<P>
<A NAME="IDX1715"></A>
<U>Function:</U> pid_t <B>waitpid</B> <I>(pid_t <VAR>pid</VAR>, int *<VAR>status_ptr</VAR>, int <VAR>options</VAR>)</I><P>
The <CODE>waitpid</CODE> function is used to request status information from a
child process whose process ID is <VAR>pid</VAR>.  Normally, the calling
process is suspended until the child process makes status information
available by terminating.
<P>
Other values for the <VAR>pid</VAR> argument have special interpretations.  A
value of <CODE>-1</CODE> or <CODE>WAIT_ANY</CODE> requests status information for
any child process; a value of <CODE>0</CODE> or <CODE>WAIT_MYPGRP</CODE> requests
information for any child process in the same process group as the
calling process; and any other negative value - <VAR>pgid</VAR>
requests information for any child process whose process group ID is
<VAR>pgid</VAR>.
<P>
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 <CODE>waitpid</CODE>
again.
<P>
The <VAR>options</VAR> argument is a bit mask.  Its value should be the
bitwise OR (that is, the <SAMP>`|'</SAMP> operator) of zero or more of the
<CODE>WNOHANG</CODE> and <CODE>WUNTRACED</CODE> flags.  You can use the
<CODE>WNOHANG</CODE> flag to indicate that the parent process shouldn't wait;
and the <CODE>WUNTRACED</CODE> flag to request status information from stopped
processes as well as processes that have terminated.
<P>
The status information from the child process is stored in the object
that <VAR>status_ptr</VAR> points to, unless <VAR>status_ptr</VAR> is a null pointer.
<P>
The return value is normally the process ID of the child process whose
status is reported.  If the <CODE>WNOHANG</CODE> option was specified and no
child process is waiting to be noticed, the value is zero.  A value of
<CODE>-1</CODE> is returned in case of error.  The following <CODE>errno</CODE>
error conditions are defined for this function:
<P>
<DL COMPACT>
<DT><CODE>EINTR</CODE>
<DD>The function was interrupted by delivery of a signal to the calling
process.  See section <A HREF="library_21.html#SEC362" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_21.html#SEC362">Primitives Interrupted by Signals</A>.
<P>
<DT><CODE>ECHILD</CODE>
<DD>There are no child processes to wait for, or the specified <VAR>pid</VAR>
is not a child of the calling process.
<P>
<DT><CODE>EINVAL</CODE>
<DD>An invalid value was provided for the <VAR>options</VAR> argument.
</DL>
<P>
These symbolic constants are defined as values for the <VAR>pid</VAR> argument
to the <CODE>waitpid</CODE> function.
<P>
<DL COMPACT>
<DT><CODE>WAIT_ANY</CODE>
<DD><P>
This constant macro (whose value is <CODE>-1</CODE>) specifies that
<CODE>waitpid</CODE> should return status information about any child process.
<P>
<DT><CODE>WAIT_MYPGRP</CODE>