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

FreeBSD Man Pages

Man Page or Keyword Search:
Man Architecture
Apropos Keyword Search (all sections) Output format
home | help
WAIT(2)			  FreeBSD System Calls Manual		       WAIT(2)

NAME
     wait, waitid, waitpid, wait3, wait4, wait6	-- wait	for processes to
     change status

LIBRARY
     Standard C	Library	(libc, -lc)

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

     pid_t
     wait(int *status);

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

     #include <sys/signal.h>

     int
     waitid(idtype_t idtype, id_t id, siginfo_t	*info, int options);

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

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

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

     pid_t
     wait6(idtype_t idtype, id_t id, int *status, int options,
	 struct	__wrusage *wrusage, siginfo_t *infop);

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 contains termination information about the process that exited as
     defined below.  The wait()	call is	the same as wait4() with a wpid	value
     of	-1, with an options value of zero, and a rusage	value of zero.

     The wait4() system	call provides a	more general interface for programs
     that need to wait for certain child processes, that need resource uti-
     lization statistics accumulated by	child processes, or that require
     options.

     The broadest interface of all functions in	this family is wait6() which
     is	otherwise very much like wait4() but with a few	very important dis-
     tinctions.	 To wait for exited processes, the option flag WEXITED need to
     be	explicitly specified.  This allows for waiting for processes which
     have experienced other status changes without having to handle also the
     exit status from the terminated processes.	 Instead of the	traditional
     rusage argument, a	pointer	to a new structure

     struct __wrusage {
	     struct rusage   wru_self;
	     struct rusage   wru_children;
     };
     can be passed.  This allows the calling process to	collect	resource usage
     statistics	from both its own child	process	as well	as from	its grand
     children.	When no	resource usage statistics are needed this pointer can
     be	NULL.  The last	argument infop must be either NULL or a	pointer	to a
     siginfo_t structure.  When	specified, the structure is filled the same as
     for SIGNCHLD signal, delivered at the process state change.
     The process, which	state is queried, is specified by two arguments	idtype
     and id.  The separate idtype and id arguments allows to support many
     other types of IDs	 as well in addition to	PID and	PGID.

	   +o   If idtype is P_PID, waitid() and	wait6()	wait for the child
	       process with a process ID equal to (pid_t)id.

	   +o   If idtype is P_PGID, waitid() and wait6() wait for the child
	       process with a process group ID equal to	(pid_t)id.

	   +o   If idtype is P_ALL, waitid() and	wait6()	wait for any child
	       process and the id is ignored.

	   +o   If idtype is P_PID or P_PGID and	the id is zero,	waitid() and
	       wait6() wait for	any child process in the same process group as
	       the caller.

     Non-standard specifiers for the process to	wait for, supported by this
     implementation of waitid()	and wait6(), are:

	   +o   The idtype value	P_UID waits for	processes which	effective UID
	       is equal	to (uid_t)id.

	   +o   The idtype value	P_GID waits for	processes which	effective GID
	       is equal	to (gid_t)id.

	   +o   The idtype value	P_SID waits for	processes which	session	ID is
	       equal to	id.  In	case the child process started its own new
	       session,	SID will be the	same as	its own	PID.  Otherwise	the
	       SID of a	child process will match the caller's SID.

	   +o   The idtype value	P_JAILID waits for processes within a jail
	       which jail identifier is	equal to id.

     For wait(), wait3(), and wait4() functions, the single wpid argument
     specifies the set of child	processes for which to wait.

	   +o   If wpid is -1, the call waits for any child process.

	   +o   If wpid is 0, the call waits for	any child process in the
	       process group of	the caller.

	   +o   If wpid is greater than zero, the call waits for	the process
	       with process id wpid.

	   +o   If wpid is less than -1,	the call waits for any process whose
	       process group id	equals the absolute value of wpid.

     The status	argument is defined below.

     The options argument contains the bitwise OR of any of the	following
     options.

     WCONTINUED
	     indicates that children of	the current process that have contin-
	     ued from a	job control stop, by receiving a SIGCONT signal,
	     should also have their status reported.

     WNOHANG
	     is	used to	indicate that the call should not block	when there are
	     no	processes wishing to report status.

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

     WSTOPPED
	     is	an alias for WUNTRACED.

     WTRAPPED
	     allows waiting for	processes which	have trapped or	reached	a
	     breakpoint.

     WEXITED
	     indicates that the	caller is wants	to receive status reports from
	     terminated	processes.  This flag is implicitly set	for the	func-
	     tions wait(), waitpid(), wait3(), and wait4().
	     For the waitid() and wait6() functions, the flag has to be
	     explicitly	included in the	options, if status reports from	termi-
	     nated processes are expected.

     WNOWAIT
	     keeps the process whose status is returned	in a waitable state.
	     The process may be	waited for again after this call completes.

     For the waitid() and wait6() functions, at	least one of the options
     WEXITED, WUNTRACED, WSTOPPED, WTRAPPED, or	WCONTINUED must	be specified.
     Otherwise there will be no	events for the call to report.	To avoid hang-
     ing indefinitely in such a	case these functions return -1 with errno set
     to	EINVAL.

     If	rusage is non-NULL, a summary of the resources used by the terminated
     process and all its children is returned.

     If	wrusage	argument is non-NULL, a	resource usage statistics from both
     its own child process as well as from its grand children is returned.

     If	infop is non-NULL, it must point to a siginfo_t	structure which	is
     filled on return such that	the si_signo field is always SIGCHLD and the
     field si_pid if be	non-zero, if there is a	status change to report.  If
     there are no status changes to report and WNOHANG is applied, both	of
     these fields are returned zero.  When using the waitid() function with
     the WNOHANG option	set, checking these fields is the only way to know
     whether there were	any status changes to report, because the return value
     from waitid() is be zero as it is for any successful return from
     waitid().

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

     The waitpid() function 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 wait6() call, with the bits WEXITED and WTRAPPED set in the
     options and with infop set	to NULL, is similar to wait4().

     The following macros may be used to test the manner of exit of the
     process.  One of the first	four 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
	     received.

     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 are pending, the call
     may be interrupted	or restarted when the signal-catching routine returns,
     depending on the options in effect	for the	signal;	see discussion of
     SA_RESTART	in sigaction(2).

     The implementation	queues one SIGCHLD signal for each child process whose
     status has	changed, if wait() returns because the status of a child
     process is	available, the pending SIGCHLD signal associated with the
     process ID	of the child process will be discarded.	 Any other pending
     SIGCHLD signals remain pending.

     If	SIGCHLD	is blocked, wait() returns because the status of a child
     process is	available, the pending SIGCHLD signal will be cleared unless
     another status of the child process is available.

RETURN VALUES
     If	wait() returns due to a	stopped, continued, 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	wait6(), wait4(), wait3(), or waitpid()	returns	due to a stopped, con-
     tinued, 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, continued or exited	children, 0 is
     returned.	If an error is detected	or a caught signal aborts the call, a
     value of -1 is returned and errno is set to indicate the error.

     If	waitid() returns because one or	more processes have a state change to
     report, 0 is returned.  To	indicate an error, -1 will be returned and
     errno set to an appropriate value.	 If WNOHANG was	used, 0	can be
     returned indicating no error, but no processes may	have changed state
     either, if	si_signo and/or	si_pid are zero.

ERRORS
     The wait()	function 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 argument points to	an illegal
			address.  (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.

     [EINVAL]		An invalid value was specified for options, or idtype
			and id do not specify a	valid set of processes.

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

STANDARDS
     The wait(), waitpid(), and	waitid() functions are defined by POSIX;
     wait6(), wait4(), and wait3() are not specified by	POSIX.	The
     WCOREDUMP() macro and the ability to restart a pending wait() call	are
     extensions	to the POSIX interface.

HISTORY
     The wait()	function appeared in Version 6 AT&T UNIX.

FreeBSD	9.3		       November	10, 2012		   FreeBSD 9.3

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

Want to link to this manual page? Use this URL:
<http://www.freebsd.org/cgi/man.cgi?query=wait6&manpath=FreeBSD+9.3-RELEASE>

home | help