path: root/manual/process.texi

@node Processes, Inter-Process Communication, Program Basics, Top
@c %MENU% How to create processes and run other programs
@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.

@cindex child process
@cindex parent process
Processes are organized hierarchically.  Each process has a @dfn{parent
process} which explicitly arranged to create it.  The processes created
by a given parent are called its @dfn{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 @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 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.
@end menu


@node Running a Command
@section 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.

@deftypefun int system (const char *@var{command})
@standards{ISO, stdlib.h}
@pindex sh
@safety{@prelim{}@mtsafe{}@asunsafe{@ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{}}}
@c system @ascuplugin @ascuheap @asulock @aculock @acsmem
@c  do_system @ascuplugin @ascuheap @asulock @aculock @acsmem
@c   sigemptyset dup ok
@c   libc_lock_lock @asulock @aculock
@c   ADD_REF ok
@c   sigaction dup ok
@c   SUB_REF ok
@c   libc_lock_unlock @aculock
@c   sigaddset dup ok
@c   sigprocmask dup ok
@c   CLEANUP_HANDLER @ascuplugin @ascuheap @acsmem
@c    libc_cleanup_region_start @ascuplugin @ascuheap @acsmem
@c     pthread_cleanup_push_defer @ascuplugin @ascuheap @acsmem
@c      __pthread_testcancel @ascuplugin @ascuheap @acsmem
@c       CANCEL_ENABLED_AND_CANCELED ok
@c       do_cancel @ascuplugin @ascuheap @acsmem
@c    cancel_handler ok
@c     kill syscall ok
@c     waitpid dup ok
@c     libc_lock_lock ok
@c     sigaction dup ok
@c     libc_lock_unlock ok
@c   FORK ok
@c    clone syscall ok
@c   waitpid dup ok
@c   CLEANUP_RESET ok
@c    libc_cleanup_region_end ok
@c     pthread_cleanup_pop_restore ok
@c  SINGLE_THREAD_P ok
@c  LIBC_CANCEL_ASYNC @ascuplugin @ascuheap @acsmem
@c   libc_enable_asynccancel @ascuplugin @ascuheap @acsmem
@c    do_cancel dup @ascuplugin @ascuheap @acsmem
@c  LIBC_CANCEL_RESET ok
@c   libc_disable_asynccancel ok
@c    lll_futex_wait dup ok
This function executes @var{command} as a shell command.  In @theglibc{},
it always uses the default shell @code{sh} to run the command.
In particular, it searches 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.

If the @var{command} argument is a null pointer, a return value of zero
indicates that no command processor is available.

This function is a cancellation 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 @code{system} is
called.  If the thread gets canceled these resources stay allocated
until the program ends.  To avoid this calls to @code{system} should be
protected using cancellation handlers.
@c ref pthread_cleanup_push / pthread_cleanup_pop

@pindex stdlib.h
The @code{system} function is declared in the header file
@file{stdlib.h}.
@end deftypefun

@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
@w{@code{system (NULL)}}; if the return value is nonzero, a command
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
@section 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 creating a process
@cindex forking a process
@cindex child process
@cindex parent process
@cindex subprocess
A new processes is created when one of the functions
@code{posix_spawn}, @code{fork}, @code{_Fork} or @code{vfork} is called.
(The @code{system} and @code{popen} also create new processes internally.)
Due to the name of the @code{fork} function, the act of creating a new
process is sometimes called @dfn{forking} a process.  Each new process
(the @dfn{child process} or @dfn{subprocess}) is allocated a process
ID, distinct from the process ID of the parent process.  @xref{Process
Identification}.

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} or
@code{waitpid} (@pxref{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 @code{fork} or @code{_Fork}
call returns.  You can use the return value from @code{fork} or
@code{_Fork} to tell whether the program is running in the parent process
or the child.

@cindex process image
Having several processes run the same program is only occasionally
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 i