Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
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 un-
       til status information for one of its  terminated  child	 processes  is
       available, or until delivery of a signal	whose action is	either to exe-
       cute 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  re-
       turn  the process status	at the time of the target process termination.
       If status information is	available prior	to the call to waitpid(),  re-
       turn will be immediate.

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

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

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

	 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 less than	(pid_t)-1, status is requested for  any	 child
	    process  whose process group  ID is	equal to the absolute value of
	    pid.

       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	termi-
       nate, and waitpid() will	fail and set errno to ECHILD.

       If  waitpid()  returns  because the status of a child process is	avail-
       able, 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	 loca-
       tion 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  con-
		       tinued, is also reported	to the calling process.

       WNOHANG	       The  waitpid()  function	 will not suspend execution of
		       the calling process if status is	not immediately	avail-
		       able 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	avail-
       able,   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	avail-
       able, and status	is not available for any  process  specified  by  pid,
       then  0 is returned.  Otherwise,	-1 is returned and errno is set	to in-
       dicate 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  re-
		       ceipt 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 iden-
       tical 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	     |Standard			   |
       +-----------------------------+-----------------------------+
       |MT-Level		     |Async-Signal-Safe		   |
       +-----------------------------+-----------------------------+

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

SunOS 5.10			  19 Jun 2003			   waitpid(3C)

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUES | ERRORS | USAGE | ATTRIBUTES | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=waitpid&sektion=3c&manpath=SunOS+5.10>

home | help