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

FreeBSD Manual Pages

  
 
  

home | help
wait3(3C)		 Standard C Library Functions		     wait3(3C)

NAME
       wait3, wait4 - wait for process to terminate or stop

SYNOPSIS
       #include	<sys/wait.h>
       #include	<sys/time.h>
       #include	<sys/resource.h>

       pid_t wait3(int *statusp, int options, struct rusage *rusage);

       pid_t  wait4(pid_t  pid,	 int  *statusp,	 int  options,	struct	rusage
       *rusage);

DESCRIPTION
       The wait3() function delays its caller until a signal  is  received  or
       one  of	its child processes terminates or stops	due to tracing.	If any
       child process has died or stopped due to	tracing	and this has  not  al-
       ready  been reported, return is immediate, returning the	process	ID and
       status of one of	those children.	If that	child process has died,	it  is
       discarded.  If  there  are  no children,	-1 is returned immediately. If
       there are only running or stopped but reported  children,  the  calling
       process is blocked.

       If  statusp  is	not  a	null pointer, then on return from a successful
       wait3() call, the status	of the child process is	stored in the  integer
       pointed	to by statusp. *statusp	indicates the cause of termination and
       other information about the terminated process in the following manner:

	 o  If the low-order 8 bits of *statusp	are equal to 0177,  the	 child
	    process  has  stopped;  the	 8 bits	higher up from the low-order 8
	    bits of *statusp contain the number	of the signal that caused  the
	    process to stop. See signal.h(3HEAD).

	 o  If the low-order 8 bits of *statusp	are non-zero and are not equal
	    to 0177, the child process terminated due to a signal; the low-or-
	    der	 7 bits	of *statusp contain the	number of the signal that ter-
	    minated the	process. In addition, if the low-order seventh bit  of
	    *statusp  (that  is,  bit  0200)  is  set, a ``core	image''	of the
	    process was	produced; see signal.h(3HEAD).

	 o  Otherwise, the child process terminated due	to an exit() call; the
	    8 bits higher up from the low-order	8 bits of *statusp contain the
	    low-order 8	bits of	the argument that the child process passed  to
	    exit(); see	exit(2).

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

       WNOHANG	       Execution of the	calling	process	is  not	 suspended  if
		       status  is  not	immediately  available	for  any child
		       process.

       WUNTRACED       The status of any child processes that are stopped, and
		       whose  status  has  not	yet  been  reported since they
		       stopped,	are also reported to the requesting process.

       If rusage is not	a null pointer,	a summary of the resources used	by the
       terminated process and all its children is returned. Only the user time
       used and	the system time	used are currently  available.	They  are  re-
       turned  in  the ru_utime	and ru_stime, members of the rusage structure,
       respectively.

       When the	WNOHANG	option is specified and	no processes  have  status  to
       report,	wait3()	 returns  0.  The WNOHANG and WUNTRACED	options	may be
       combined	by the bitwise OR operation of the two values.

       The wait4() function is an extended interface.  With a pid argument  of
       0,  it  is  equivalent  to  wait3().  If	 pid has a nonzero value, then
       wait4() returns status only for the indicated process ID, but  not  for
       any other child processes. The status can be evaluated using the	macros
       defined by wait.h(3HEAD).

RETURN VALUES
       If wait3() or wait4() returns due to  a	stopped	 or  terminated	 child
       process,	 the  process  ID  of  the  child  is  returned	to the calling
       process.	Otherwise, -1 is returned and errno is set to indicate the er-
       ror.

       If  wait3()  or	wait4()	 return	due to the delivery of a signal	to the
       calling process,	-1 is returned and errno is set	to EINTR.  If  WNOHANG
       was  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, 0 is returned. Otherwise, -1 is returned and
       errno is	set to indicate	the error.

       The wait3() and wait4() functions return	0 if WNOHANG is	specified  and
       there  are  no stopped or exited	children, and return the process ID of
       the child process if they return	due to a stopped or  terminated	 child
       process.	Otherwise, they	return -1 and set errno	to indicate the	error.

ERRORS
       The wait3() and wait4() functions will fail and return immediately if:

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

       EFAULT	       The statusp or rusage arguments point to	an illegal ad-
		       dress.

       EINTR	       The  function was interrupted by	a signal. The value of
		       the location pointed to by statusp is undefined.

       EINVAL	       The value of options is not valid.

       The wait4() function may	fail if:

       ECHILD	       The process specified by	pid does not exist or is not a
		       child of	the calling process.

       The wait3()and wait4() functions	will terminate prematurely, return -1,
       and set errno to	EINTR upon the arrival of a  signal  whose  SA_RESTART
       bit in its flags	field is not set (see sigaction(2)).

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

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE	TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |MT-Level		     |Async-Signal-Safe		   |
       +-----------------------------+-----------------------------+

SEE ALSO
       kill(1),	 exit(2),  waitid(2), waitpid(3C),  getrusage(3C), signal(3C),
       signal.h(3HEAD),	wait(3C), wait.h(3HEAD), proc(4)

NOTES
       If a parent process terminates without waiting  on  its	children,  the
       initialization process (process ID = 1) inherits	the children.

       The  wait3()  and  wait4() functions are	automatically restarted	when a
       process receives	 a  signal  while  awaiting  termination  of  a	 child
       process,	 unless	 the  SA_RESTART  bit is not set in the	flags for that
       signal.

SunOS 5.10			  3 Mar	1995			     wait3(3C)

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

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

home | help