wait(2)								      wait(2)



NAME

  wait, waitpid, wait3, wait4 - Waits for a child process to stop or ter-
  minate

SYNOPSIS

  #include 
  #include 
  pid_t wait (
	  int *status_location );
  pid_t waitpid (
	  pid_t process_id,
	  int *status_location,
	  int options );
  #include 
  pid_t wait3 (
	  union wait *status_location,
	  int options,
	  struct rusage *resource_usage );
  pid_t wait4 (
	  pid_t process_id
	  union wait *status_location,
	  int options,
	  struct rusage *resource_usage );

PARAMETERS

  status_location
	    Points to a location that contains the termination status of the
	    child process as defined in the  header file.

  process_id
	    Specifies the child process or set of child processes.

  options   Modifies the behavior of the function. The flags for the options
	    parameter are defined in the DESCRIPTION section.

  resource_usage
	    Specifies the location of a structure that will contain the
	    resource utilization information for child processes that have
	    terminated.

DESCRIPTION

  The wait function suspends the calling process until it receives a signal
  that is to be caught, or until any one of the calling process's child
  processes stops or terminates.  Any condition that leads to an ECHILD error
  causes all the wait variants to return immediately with a status of -1.
  The wait function also returns immediately if a child process (not waited
  for) has stopped, terminated, or continued prior to the call.


  The effect of the wait function can be modified by setting the SIGCHLD sig-
  nal.	(See the sigaction(2) for more information).

  The waitpid function behaves the same as the wait function only if the
  process_id parameter has a value of -1 and the options parameter specifies
  a value of zero (0).	Should these parameters contain other values, the
  waitpid function is changed as specified by those values.

  The wait, waitpid, wait3, and wait4 functions, which suspend the calling
  process until the request is completed, are redefined so that only the cal-
  ling thread is suspended.

  The process_id parameter allows the calling process to gather status from a
  specific set of child processes, according to the following rules:

    +  If the process_id parameter is equal to-1, status is requested for any
       child process.  In this respect, the waitpid function is equivalent to
       the wait function.

    +  If the process_id parameter is greater than zero (0), it specifies the
       process ID of a single child process for which status is requested.

    +  If the process_id parameter is equal to zero (0), status is requested
       for any child process whose process group ID is equal to that of the
       calling process.

    +  If the process_id parameter is less than-1, status is requested for
       any child process whose process group ID is equal to the absolute
       value of the process_id parameter.

  The waitpid and wait4 functions will only return the status of a child pro-
  cess from this set.

  The options parameter to the waitpid, wait3, and wait4 functions modifies
  the behavior of the function.	 The flags for the options parameter can be
  combined by specifying their bitwise-inclusive OR.  The flags are as fol-
  lows:

  WCONTINUED
	    Specifies that the status of any continued child process that was
	    specified by the process_id parameter whose status has not been
	    reported since it continued will be reported to the calling pro-
	    cess.

  WNOWAIT   Specifies that the process whose status is returned in
	    status_location will be kept in a waitable state will be kept.
	    The process can be waited for again with the same results.

  WNOHANG   Prevents the calling process from being suspended.	If there are
	    child processes that have been stopped or terminated, one is
	    chosen and waitpid returns its pid, just as when the WNOHANG flag
	    is not specified.  If there are no such processes (that is, if
	    conditions are such that waitpid without the WNOHANG flag would
	    have suspended the calling process), zero (0) is returned.
	    Because you can never wait for process 0, there is no confusion
	    arising from this return.

  WUNTRACED Specifies that the call return additional information when the
	    child processes of the current process are stopped because they
	    received a SIGTTIN, SIGTTOU, SIGSTOP, or SIGTSTOP signal.

  If the wait, waitpid, wait3, or wait4 function returns because the status
  of a child process is available, the process ID of the child process is
  returned.  In this instance, information is stored in the location pointed
  to by the status_location parameter if the value of the status_location is
  not null.  The value stored in the location pointed to by the
  status_location parameter is zero (0) if, and only if the status is
  returned from a terminated child process that did one of the following:

    +  Returned zero (0) from the main() routine.

    +  Passed zero (0) as the status parameter to the _exit or exit function.

  Regardless of its value, this information can be defined using the macros
  defined in the  header file that evaluate to integral expres-
  sions.  In the following macro descriptions, the status_value parameter is
  equal to the integer value pointed to by the status_location parameter:

  WIFEXITED(status_value)
	    Evaluates to a nonzero value if status was returned for a child
	    process that terminated normally.

  WEXITSTATUS(status_value)
	    If the value of WIFEXITED(status_value) is nonzero, this macro
	    evaluates to the low-order 8 bits of the status parameter that
	    the child process passed to the _exit or exit function, or the
	    value the child process returned from the main() routine.

  WIFSIGNALED(status_value)
	    Evaluates to nonzero value if status was returned for a child
	    process that terminated due to the receipt of a signal that was
	    not caught.

  WTERMSIG(status_value)
	    If the value of WIFSIGNALED(status_value) is nonzero, this macro
	    evaluates to the number of the signal that caused the termination
	    of the child process.

  WIFSTOPPED(status_value)
	    Evaluates to a nonzero value if status was returned for a child
	    process that is currently stopped.

  WSTOPSIG(status_value)
	    If the value of WIFSTOPPED(status_value) is nonzero, this macro
	    evaluates to the number of the signal that caused the child pro-
	    cess to stop.

  WIFCONTINUED(status_value)
	    Evaluates to a non-zero value if status was returned for a child
	    process that has continued.

  If the information stored at the location pointed to by the status_location
  parameter was stored there by a call to the waitpid, wait3, or the wait4
  function that specified the WUNTRACED flag, one of the following macros
  evaluates to a nonzero value:

    +  WIFEXITED(*status_value)

    +  WIFSIGNALED(*status_value)

    +  WIFSTOPPED(*status_value)

    +  WIFCONTINUED(*status_value)

  If the information stored in the buffer pointed to by the status_location
  parameter resulted from a call to the wait function or a call to the wait-
  pid, wait3, or wait4 function without the WUNTRACED flag specified, one of
  the following macros evaluates to a nonzero value:

    +  WIFEXITED(*status_value)

    +  WIFSIGNALED(*status_value)

  The wait3 function provides compatibility with BSD systems.  A program that
  calls wait3 must be compiled with the _BSD switch defined.  In this case,
  the parameter to the macros described previously should be the w_status
  member of the union pointed to by the status_location parameter.  The wait3
  and wait4 functions also include a resource_usage parameter.	This
  parameter points to a location that contains resource usage information for
  the child process as defined in the  header file.

  The wait4 function is similar to wait3.  However, the wait4 function waits
  for a specific child as indicated by the process_id parameter.  A program
  that calls wait4 must be compiled with the _BSD switch defined; see the
  previous paragraph for further information.

  If a parent process terminates without waiting for all of its child
  processes to terminate, the remaining child processes will be assigned a
  parent process ID equal to the process ID of the init process.

NOTES

  Compiling with the _BSD switch defined and then linking with the libbsd
  compatibility library redefines the status_location parameter as the type
  union wait * instead of int *.  Programs using the wait3 and wait4 func-
  tions must be compiled and linked in this manner.

  AES Support Level:
		 Full use (wait, waitpid)

ERRORS

  If the wait, waitpid, wait3, or wait4 function fails, errno can be set to
  one of the following values:

  [ECHILD]  The calling process has no existing unwaited-for child processes.

  [EINTR]   The function was terminated by receipt of a signal.

  [EFAULT]  The status_location or resource_usage parameter points to a loca-
	    tion outside of the address space of the process.

  The waitpid function fails if one or both of the following are true:

  [ECHILD]  The process or process group ID specified by the process_id
	    parameter does not exist or is not a child process of the calling
	    process.

  The waitpid, wait3, or wait4 functions fail if the following is true:

  [EINVAL]  The value of the options parameter is not valid.

RETURN VALUES

  If the wait, waitpid, wait3, or wait4 function returns because the status
  of a child process is available, the process ID of the child is returned to
  the calling process. If they return because a signal was caught by the cal-
  ling process, -1 is returned and errno is set to [EINTR].

  If the WNOHANG option was specified, and there are no stopped or exited
  child processes, the waitpid, wait3, and wait4 functions return a value of
  zero (0). Otherwise,-1 is returned and errno is set to indicate the error.

RELATED INFORMATION

  Functions: exec(2), exit(2), fork(2), ptrace(2), getrusage(2), sigac-
  tion(2).

  Routines: pause(3).