process.texi

一个C源代码分析器

@item
Pending alarms.  @xref{Setting an Alarm}.

@item
Current working directory and root directory.  @xref{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.

@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{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 @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 I/O}.

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} (@pxref{Descriptors
and Streams}).

@node Process Completion
@section 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 eligible child processes, 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, the value is zero.  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.  @xref{Interrupted Primitives}.

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

@comment Extra blank lines make it look better.
@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.
@end table

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.

@table @code
@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 flag specifies that @code{waitpid} should report the status of any
child processes that have been stopped as well as those that have
terminated.
@end table

@comment sys/wait.h
@comment POSIX.1
@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.  The call:

@smallexample
wait (&status)
@end smallexample

@noindent
is exactly equivalent to:

@smallexample
waitpid (-1, &status, 0)
@end smallexample
@end deftypefun

@comment sys/wait.h
@comment BSD
@deftypefun pid_t wait4 (pid_t @var{pid}, int *@var{status-ptr}, int @var{options}, struct rusage *@var{usage})
If @var{usage} is a null pointer, @code{wait4} is equivalent to
@code{waitpid (@var{pid}, @var{status-ptr}, @var{options})}.

If @var{usage} is not null, @code{wait4} stores usage figures for the
child process in @code{*@var{rusage}} (but only if the child has
terminated, not if it has stopped).  @xref{Resource Usage}.

This function is a BSD extension.
@end deftypefun

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 a handler for @code{SIGCHLD}, the signal that
indicates that at least one child process has terminated.

@smallexample
@group
void
sigchld_handler (int signum)
@{
  int pid;
  int status;
  while (1)
    @{
      pid = waitpid (WAIT_ANY, &status, WNOHANG);
      if (pid < 0)
        @{
          perror ("waitpid");
          break;
        @}
      if (pid == 0)
        break;
      notice_termination (pid, status);
    @}
@}
@end group
@end smallexample

@node Process Completion Status
@section 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 nonzero 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.
@xref{Exit Status}.
@end deftypefn

@comment sys/wait.h
@comment POSIX.1
@deftypefn Macro int WIFSIGNALED (int @var{status})
This macro returns a nonzero value if the child process terminated
because it received a signal that was not handled.
@xref{Signal Handling}.
@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
signal 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 nonzero 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 nonzero 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
signal number of the signal that caused the child process to stop.
@end deftypefn


@node BSD Wait Functions
@section BSD Process Wait 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 GNU
C Library defines macros such as @code{WEXITSTATUS} 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 {Data Type} {union wait}
This data type represents program termination status values.  It has
the following members:

@table @code
@item int w_termsig
The value of this member is the same as the result of the
@code{WTERMSIG} macro.

@item int w_coredump
The value of this member is the same as the result of the
@code{WCOREDUMP} macro.

@item int w_retcode
The value of this member is the same as the result of the
@code{WEXITSTATUS} macro.

@item int w_stopsig
The value of this member is the same as the result of the
@code{WSTOPSIG} macro.
@end table

Instead of accessing these members directly, you should use the
equivalent macros.
@end deftp

The @code{wait3} function is the predecessor to @code{wait4}, which is
more flexible.  @code{wait3} is now obsolete.

@comment sys/wait.h
@comment BSD
@deftypefun pid_t wait3 (union wait *@var{status-ptr}, int @var{options}, struct rusage *@var{usage})
If @var{usage} is a null pointer, @code{wait3} is equivalent to
@code{waitpid (-1, @var{status-ptr}, @var{options})}.

If @var{usage} is not null, @code{wait3} stores usage figures for the
child process in @code{*@var{rusage}} (but only if the child has
terminated, not if it has stopped).  @xref{Resource Usage}.
@end deftypefun

@node Process Creation Example
@section 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}}.

@smallexample
#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"

@group
int 
my_system (const char *command)
@{
  int status;
  pid_t pid;
@end group

  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 smallexample

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

Call @code{_exit} to accomplish this.  The reason for using @code{_exit}
instead of @code{exit} is to avoid flushing fully buffered streams such
as @code{stdout}.  The buffers of these streams probably contain data
that was copied from the parent process by the @code{fork}, data that
will be output eventually by the parent process.  Calling @code{exit} in
the child would output the data twice.  @xref{Termination Internals}.