<!-- This HTML file has been created by texi2html 1.27
     from library.texinfo on 3 March 1994 -->

<TITLE>The GNU C Library - Child Processes</TITLE>
<P>Go to the <A HREF="library_22.html" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_22.html">previous</A>, <A HREF="library_24.html" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_24.html">next</A> section.<P>
<H1><A NAME="SEC401" HREF="library_toc.html#SEC401" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC401">Child Processes</A></H1>
<A NAME="IDX1680"></A>
<P>
<DFN>Processes</DFN> 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.
<A NAME="IDX1681"></A>
<A NAME="IDX1682"></A>
<P>
Processes are organized hierarchically.  Each process has a <DFN>parent
process</DFN> which explicitly arranged to create it.  The processes created
by a given parent are called its <DFN>child processes</DFN>.  A child
inherits many of its attributes from the parent process.
<P>
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.
<P>
The <CODE>system</CODE> 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.
<P>
<A NAME="IDX1683"></A>
<H2><A NAME="SEC402" HREF="library_toc.html#SEC402" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC402">Running a Command</A></H2>
<P>
The easy way to run another program is to use the <CODE>system</CODE>
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.
<P>
<A NAME="IDX1684"></A>
<A NAME="IDX1685"></A>
<U>Function:</U> int <B>system</B> <I>(const char *<VAR>command</VAR>)</I><P>
This function executes <VAR>command</VAR> as a shell command.  In the GNU C
library, it always uses the default shell <CODE>sh</CODE> to run the command.
In particular, it searches the directories in <CODE>PATH</CODE> to find
programs to execute.  The return value is <CODE>-1</CODE> if it wasn't
possible to create the shell process, and otherwise is the status of the
shell process.  See section <A HREF="library_23.html#SEC407" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_23.html#SEC407">Process Completion</A>, for details on how this
status code can be interpreted.
<A NAME="IDX1686"></A>
<P>
The <CODE>system</CODE> function is declared in the header file
<TT>`stdlib.h'</TT>.
<P>
<STRONG>Portability Note:</STRONG> 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 (NULL)</CODE>; if the return value is nonzero, a command
processor is available.
<P>
The <CODE>popen</CODE> and <CODE>pclose</CODE> functions (see section <A HREF="library_14.html#SEC213" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_14.html#SEC213">Pipe to a Subprocess</A>) are closely related to the <CODE>system</CODE> function.  They
allow the parent process to communicate with the standard input and
output channels of the command being executed.
<P>
<H2><A NAME="SEC403" HREF="library_toc.html#SEC403" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC403">Process Creation Concepts</A></H2>
<P>
This section gives an overview of processes and of the steps involved in
creating a process and making it run another program.
<A NAME="IDX1687"></A>
<A NAME="IDX1688"></A>
<P>
Each process is named by a <DFN>process ID</DFN> number.  A unique process ID
is allocated to each process when it is created.  The <DFN>lifetime</DFN> 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.
<A NAME="IDX1689"></A>
<A NAME="IDX1690"></A>
<A NAME="IDX1691"></A>
<A NAME="IDX1692"></A>
<P>
Processes are created with the <CODE>fork</CODE> system call (so the operation
of creating a new process is sometimes called <DFN>forking</DFN> a process).
The <DFN>child process</DFN> created by <CODE>fork</CODE> is an exact clone of the
original <DFN>parent process</DFN>, except that it has its own process ID.
<P>
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 <CODE>wait</CODE> or
<CODE>waitpid</CODE> (see section <A HREF="library_23.html#SEC407" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_23.html#SEC407">Process Completion</A>).  These functions give you
limited information about why the child terminated--for example, its
exit status code.
<P>
A newly forked child process continues to execute the same program as
its parent process, at the point where the <CODE>fork</CODE> call returns.
You can use the return value from <CODE>fork</CODE> to tell whether the program
is running in the parent process or the child.
<A NAME="IDX1693"></A>
<P>
Having several processes run the same program is only occasionally
useful.  But the child can execute another program using one of the
<CODE>exec</CODE> functions; see section <A HREF="library_23.html#SEC406" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_23.html#SEC406">Executing a File</A>.  The program that the
process is executing is called its <DFN>process image</DFN>.  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.
<P>
<H2><A NAME="SEC404" HREF="library_toc.html#SEC404" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC404">Process Identification</A></H2>
<P>
The <CODE>pid_t</CODE> data type represents process IDs.  You can get the
process ID of a process by calling <CODE>getpid</CODE>.  The function
<CODE>getppid</CODE> returns the process ID of the parent of the current
process (this is also known as the <DFN>parent process ID</DFN>).  Your
program should include the header files <TT>`unistd.h'</TT> and
<TT>`sys/types.h'</TT> to use these functions.
<A NAME="IDX1695"></A>
<A NAME="IDX1694"></A>
<P>
<A NAME="IDX1696"></A>
<U>Data Type:</U> <B>pid_t</B><P>
The <CODE>pid_t</CODE> data type is a signed integer type which is capable
of representing a process ID.  In the GNU library, this is an <CODE>int</CODE>.
<P>
<A NAME="IDX1697"></A>
<U>Function:</U> pid_t <B>getpid</B> <I>(void)</I><P>
The <CODE>getpid</CODE> function returns the process ID of the current process.
<P>
<A NAME="IDX1698"></A>
<U>Function:</U> pid_t <B>getppid</B> <I>(void)</I><P>
The <CODE>getppid</CODE> function returns the process ID of the parent of the
current process.
<P>
<H2><A NAME="SEC405" HREF="library_toc.html#SEC405" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC405">Creating a Process</A></H2>
<P>
The <CODE>fork</CODE> function is the primitive for creating a process.
It is declared in the header file <TT>`unistd.h'</TT>.
<A NAME="IDX1699"></A>
<P>
<A NAME="IDX1700"></A>
<U>Function:</U> pid_t <B>fork</B> <I>(void)</I><P>
The <CODE>fork</CODE> function creates a new process.
<P>
If the operation is successful, there are then both parent and child
processes and both see <CODE>fork</CODE> return, but with different values: it
returns a value of <CODE>0</CODE> in the child process and returns the child's
process ID in the parent process.
<P>
If process creation failed, <CODE>fork</CODE> returns a value of <CODE>-1</CODE> in
the parent process.  The following <CODE>errno</CODE> error conditions are
defined for <CODE>fork</CODE>:
<P>
<DL COMPACT>
<DT><CODE>EAGAIN</CODE>
<DD>There aren't enough system resources to create another process, or the
user already has too many processes running.
<P>
<DT><CODE>ENOMEM</CODE>
<DD>The process requires more space than the system can supply.
</DL>
<P>
The specific attributes of the child process that differ from the
parent process are:
<P>
<UL>
<LI>
The child process has its own unique process ID.
<P>
<LI>
The parent process ID of the child process is the process ID of its
parent process.
<P>
<LI>
The child process gets its own copies of the parent process's open file
descriptors.  Subsequently changing attributes of the file descriptors
in the parent process won't affect the file descriptors in the child,
and vice versa.  See section <A HREF="library_12.html#SEC181" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_12.html#SEC181">Control Operations on Files</A>.
<P>
<LI>
The elapsed processor times for the child process are set to zero;
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>.
<P>
<LI>
The child doesn't inherit file locks set by the parent process.
See section <A HREF="library_12.html#SEC181" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_12.html#SEC181">Control Operations on Files</A>.
<P>
<LI>
The child doesn't inherit alarms set by the parent process.
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>
The set of pending signals (see section <A HREF="library_21.html#SEC334" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_21.html#SEC334">How Signals Are Delivered</A>) for the child
process is cleared.  (The child process inherits its mask of blocked
signals and signal actions from the parent process.)
</UL>
<P>
<A NAME="IDX1701"></A>
<U>Function:</U> pid_t <B>vfork</B> <I>(void)</I><P>
The <CODE>vfork</CODE> function is similar to <CODE>fork</CODE> but more efficient;
however, there are restrictions you must follow to use it safely.
<P>
While <CODE>fork</CODE> makes a complete copy of the calling process's address
space and allows both the parent and child to execute independently,
<CODE>vfork</CODE> does not make this copy.  Instead, the child process
created with <CODE>vfork</CODE> shares its parent's address space until it calls
one of the <CODE>exec</CODE> functions.  In the meantime, the parent process
suspends execution.
<P>
You must be very careful not to allow the child process created with
<CODE>vfork</CODE> 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</CODE>!  This
would leave the parent process's control information very confused.  If
in doubt, use <CODE>fork</CODE> instead.
<P>
Some operating systems don't really implement <CODE>vfork</CODE>.  The GNU C
library permits you to use <CODE>vfork</CODE> on all systems, but actually
executes <CODE>fork</CODE> if <CODE>vfork</CODE> isn't available.  If you follow
the proper precautions for using <CODE>vfork</CODE>, your program will still
work even if the system uses <CODE>fork</CODE> instead.
<P>
<A NAME="IDX1702"></A>
<A NAME="IDX1703"></A>
<H2><A NAME="SEC406" HREF="library_toc.html#SEC406" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC406">Executing a File</A></H2>