waitpid(3C)						   Standard C Library Functions 					       waitpid(3C)

NAME

       waitpid - wait for child process to change state

SYNOPSIS

       #include <sys/types.h>
       #include <sys/wait.h>

       pid_t waitpid(pid_t pid, int *stat_loc, int options);

DESCRIPTION

       The  waitpid()  function will suspend execution of the calling thread until status information for one of its terminated child processes is
       available, or until delivery of a signal whose action is either to execute a signal-catching function or to terminate the process. If  more
       than  one thread is suspended in waitpid(), wait(3C), or waitid(2) awaiting termination of the same process, exactly one thread will return
       the process status at the time of the target process termination. If status information is available prior to the call to waitpid(), return
       will be immediate.

       The pid argument specifies a set of child processes for which status is requested, as follows:

	   o	  If  pid is less than (pid_t)-1, status is requested for any child process whose process group  ID is equal to the absolute value
		  of pid.

	   o	  If pid is equal to (pid_t)-1, status is requested for any child process.

	   o	  If  pid is equal to (pid_t)0 status is requested for any child process whose process group  ID is equal to that of  the  calling
		  process.

	   o	  If  pid is greater than (pid_t)0, it specifies the process ID of the child process for which status is requested.

       One  instance  of  a SIGCHLD signal is queued for each child process whose status has changed. If waitpid() returns because the status of a
       child process is available, and WNOWAIT was not specified in options, any pending SIGCHLD signal associated with the  process  ID  of  that
       child process is discarded. Any other pending SIGCHLD signals remain pending.

       If  the	calling  process has SA_NOCLDWAIT set or has SIGCHLD set to SIG_IGN and the process has no unwaited children that were transformed
       into zombie processes, it will block until all of its children terminate, and waitpid() will fail and set errno to ECHILD.

       If waitpid() returns because the status of a child process is available, then that  status may be evaluated  with  the  macros  defined	by
       wait.h(3HEAD)  If  the  calling	process  had specified a non-zero value of stat_loc, the status of the child process will be stored in the
       location pointed to by stat_loc.

       The options argument is constructed from the bitwise-inclusive OR  of  zero  or	more  of  the  following  flags,  defined  in  the  header
       <sys/wait.h>:

       WCONTINUED    The  status  of  any continued child process specified by pid, whose status has not been reported since it continued, is also
		     reported to the calling process.

       WNOHANG	     The waitpid() function will not suspend execution of the calling process if status is not immediately available  for  one	of
		     the child processes specified by pid.

       WNOWAIT	     Keep the process whose status is returned in stat_loc in a waitable state. The process may be waited for again with identical
		     results.

       WUNTRACED     The status of any child processes specified by pid that are stopped, and whose status has not yet been  reported  since  they
		     stopped, is also reported to the calling process. WSTOPPED is a synonym for WUNTRACED.

RETURN VALUES

       If  waitpid()  returns because the status of a child process is available,  it returns a value equal to the process ID of the child process
       for which status is reported.  If waitpid() returns due to the delivery of a signal to the calling process, -1 is returned and errno is set
       to  EINTR.   If	waitpid() was invoked with WNOHANG set in options, it has at  least one child process specified by pid for which status is
       not available, and status is not available for any process specified by pid, then 0 is returned.  Otherwise, -1 is returned  and  errno	is
       set to indicate the error.

ERRORS

       The waitpid() function will fail if:

       ECHILD	 The  process  or  process  group  specified by pid does not exist or is not a child of the calling process or can never be in the
		 states specified by options.

       EINTR	 The waitpid() function was interrupted due to the receipt of a signal sent by the calling process.

       EINVAL	 An invalid value was specified for options.

USAGE

       With options equal to 0 and  pid equal to (pid_t)-1, waitpid() is identical to wait(3C). The waitpid() function is implemented as a call to
       the more general waitid(2) function.

ATTRIBUTES

       See attributes(5) for descriptions of the following attributes:

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |Interface Stability	     |Committed 		   |
       +-----------------------------+-----------------------------+
       |MT-Level		     |Async-Signal-Safe 	   |
       +-----------------------------+-----------------------------+
       |Standard		     |See standards(5). 	   |
       +-----------------------------+-----------------------------+

SEE ALSO

       Intro(2),   exec(2),   exit(2),	fork(2),  pause(2),  sigaction(2),  ptrace(3C),  signal(3C),  siginfo.h(3HEAD),  wait(3C),  wait.h(3HEAD),
       attributes(5), standards(5)

SunOS 5.11							    7 Dec 2007							       waitpid(3C)