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

FreeBSD Manual Pages

  
 
  

home | help
WAIT(2)			  FreeBSD System Calls Manual		       WAIT(2)

NAME
     wait, waitpid, wait4, wait3, WCOREDUMP, WEXITSTATUS, WIFCONTINUED,
     WIFEXITED,	WIFSIGNALED, WIFSTOPPED, WSTOPSIG, WTERMSIG -- wait for
     process termination

SYNOPSIS
     #include <sys/wait.h>

     pid_t
     wait(int *status);

     pid_t
     waitpid(pid_t wpid, int *status, int options);

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

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

     pid_t
     wait4(pid_t wpid, int *status, int	options, struct	rusage *rusage);

DESCRIPTION
     The wait()	function suspends execution of its calling process until
     status information	is available for a terminated child process, or	a sig-
     nal is received.  On return from a	successful wait() call,	the status
     area, if non-zero,	is filled in with termination information about	the
     process that exited (see below).

     The wait4() call provides a more general interface	for programs that need
     to	wait for certain child processes, that need resource utilization sta-
     tistics accumulated by child processes, or	that require options.  The
     other wait	functions are implemented using	wait4().

     The wpid parameter	specifies the set of child processes for which to
     wait.  The	following symbolic constants are currently defined in
     <sys/wait.h>:

	   #define WAIT_ANY	   (-1)	   /* any process */
	   #define WAIT_MYPGRP	   0	   /* any process in my	process	group */

     If	wpid is	set to WAIT_ANY, the call waits	for any	child process.	If
     wpid is set to WAIT_MYPGRP, the call waits	for any	child process in the
     process group of the caller.  If wpid is greater than zero, the call
     waits for the process with	process	ID wpid.  If wpid is less than -1, the
     call waits	for any	process	whose process group ID equals the absolute
     value of wpid.

     The status	parameter is defined below.  The options argument is the bit-
     wise OR of	zero or	more of	the following values:

     WCONTINUED	 Causes	status to be reported for stopped child	processes that
		 have been continued by	receipt	of a SIGCONT signal.

     WNOHANG	 Indicates that	the call should	not block if there are no pro-
		 cesses	that wish to report status.

     WUNTRACED	 If set, children of the current process that are stopped due
		 to a SIGTTIN, SIGTTOU,	SIGTSTP, or SIGSTOP signal also	have
		 their status reported.

     If	rusage is non-zero, a summary of the resources used by the terminated
     process and all its children is returned (this information	is currently
     not available for stopped processes).

     When the WNOHANG option is	specified and no processes wish	to report sta-
     tus, wait4() returns a process ID of 0.

     The waitpid() call	is identical to	wait4()	with an	rusage value of	zero.
     The older wait3() call is the same	as wait4() with	a wpid value of	-1.

     The following macros may be used to test the manner of exit of the
     process.  One of the first	three macros will evaluate to a	non-zero
     (true) value:

     WIFCONTINUED(status)
	     True if the process has not terminated, and has continued after a
	     job control stop.	This macro can be true only if the wait	call
	     specified the WCONTINUED option.

     WIFEXITED(status)
	     True if the process terminated normally by	a call to _exit(2) or
	     exit(3).

     WIFSIGNALED(status)
	     True if the process terminated due	to receipt of a	signal.

     WIFSTOPPED(status)
	     True if the process has not terminated, but has stopped and can
	     be	restarted.  This macro can be true only	if the wait call spec-
	     ified the WUNTRACED option	or if the child	process	is being
	     traced (see ptrace(2)).

     Depending on the values of	those macros, the following macros produce the
     remaining status information about	the child process:

     WEXITSTATUS(status)
	     If	WIFEXITED(status) is true, evaluates to	the low-order 8	bits
	     of	the argument passed to _exit(2)	or exit(3) by the child.

     WTERMSIG(status)
	     If	WIFSIGNALED(status) is true, evaluates to the number of	the
	     signal that caused	the termination	of the process.

     WCOREDUMP(status)
	     If	WIFSIGNALED(status) is true, evaluates as true if the termina-
	     tion of the process was accompanied by the	creation of a core
	     file containing an	image of the process when the signal was re-
	     ceived.

     WSTOPSIG(status)
	     If	WIFSTOPPED(status) is true, evaluates to the number of the
	     signal that caused	the process to stop.

NOTES
     See sigaction(2) for a list of termination	signals.  A status of 0	indi-
     cates normal termination.

     If	a parent process terminates without waiting for	all of its child pro-
     cesses to terminate, the remaining	child processes	are assigned the par-
     ent process 1 ID (the init	process	ID).

     If	a signal is caught while any of	the wait() calls is pending, the call
     may be interrupted	or restarted when the signal-catching routine returns,
     depending on the options in effect	for the	signal;	for further informa-
     tion, see siginterrupt(3).

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

     If	wait4(), wait3() or waitpid() returns due to a stopped or terminated
     child process, the	process	ID of the child	is returned to the calling
     process.  If there	are no children	not previously awaited,	-1 is returned
     with errno	set to [ECHILD].  Otherwise, if	WNOHANG	is specified and there
     are no stopped or exited children,	0 is returned.	If an error is de-
     tected or a caught	signal aborts the call,	a value	of -1 is returned and
     errno is set to indicate the error.

ERRORS
     wait(), waitpid(),	wait3(), and wait4() will fail and return immediately
     if:

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

     [ECHILD]		No status from the terminated child process is avail-
			able because the calling process has asked the system
			to discard such	status by ignoring the signal SIGCHLD
			or setting the flag SA_NOCLDWAIT for that signal.

     [EFAULT]		The status or rusage arguments point to	an illegal ad-
			dress.	(May not be detected before exit of a child
			process.)

     [EINTR]		The call was interrupted by a caught signal, or	the
			signal did not have the	SA_RESTART flag	set.

     waitpid() and wait4() will	fail and return	immediately if:

     [ECHILD]		The process specified by the wpid argument does	not
			exist or is not	a child	of the calling process.

     [EINVAL]		Invalid	or undefined flags were	passed in the options
			argument.

SEE ALSO
     _exit(2), sigaction(2), exit(3)

STANDARDS
     The wait()	and waitpid() functions	conform	to IEEE	Std 1003.1-2008
     ("POSIX.1").

     wait4() and wait3() are not specified by POSIX.  The WCOREDUMP() macro
     and the ability to	restart	a pending wait() call are extensions to	that
     specification.

HISTORY
     A wait() system call first	appeared in Version 1 AT&T UNIX.  The status
     argument is accepted since	Version	2 AT&T UNIX.  A	wait3()	system call
     first appeared in 4BSD, but the final calling convention was only estab-
     lished in 4.2BSD.	The wait4() and	waitpid() function calls first ap-
     peared in 4.3BSD-Reno.

FreeBSD	13.0			  May 1, 2017			  FreeBSD 13.0

NAME | SYNOPSIS | DESCRIPTION | NOTES | RETURN VALUES | ERRORS | SEE ALSO | STANDARDS | HISTORY

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=wait&sektion=2&manpath=OpenBSD+6.9>

home | help