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

FreeBSD Manual Pages

  
 
  

home | help
WAIT(2V)							      WAIT(2V)

NAME
       wait, wait3, wait4, waitpid, WIFSTOPPED,	WIFSIGNALED, WIFEXITED,	WEXIT-
       STATUS, WTERMSIG, WSTOPSIG - wait for process to	terminate or stop, ex-
       amine returned status

SYNOPSIS
       #include	<sys/wait.h>

       int wait(statusp)
       int *statusp;

       int waitpid(pid,	statusp, options)
       int pid;
       int *statusp;
       int options;

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

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

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

       WIFSTOPPED(status)
       int status;

       WIFSIGNALED(status)
       int status;

       WIFEXITED(status)
       int status

       WEXITSTATUS(status)
       int status

       WTERMSIG(status)
       int status

       WSTOPSIG(status)
       int status

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

       pid_t wait(statusp)
       int *statusp;

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

DESCRIPTION
       wait() delays its caller	until a	signal is received or one of its child
       processes terminates or stops due to tracing.  If any child has died or
       stopped due to tracing and this has not been reported using wait(), re-
       turn is immediate, returning the	process	ID and exit status of  one  of
       those children.	If that	child had died,	it is discarded.  If there are
       no children, return is immediate	with the value -1 returned.  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
       wait() call the status of the child process whose process ID is the re-
       turn value of wait() is stored in the location pointed to  by  statusp.
       It  indicates  the cause	of termination and other information about the
       terminated process in the following manner:

	      o	 If the	first byte (the	low-order 8 bits) are equal  to	 0177,
		 the  child  process  has stopped.  The	next byte contains the
		 number	of the signal that caused the process  to  stop.   See
		 ptrace(2) and sigvec(2).

	      o	 If the	first byte (the	low-order 8 bits) are non-zero and are
		 not equal to 0177, the	child process terminated due to	a sig-
		 nal.	The  low-order 7 bits contain the number of the	signal
		 that terminated the process.  In addition, if	the  low-order
		 seventh  bit  (that is, bit 0200) is set, a ``core image'' of
		 the process was produced (see sigvec(2)).

	      o	 Otherwise, the	child process terminated  due  to  a  call  to
		 exit(2V).  The	next byte contains the low-order 8 bits	of the
		 argument that the child process passed	to exit().

       waitpid() behaves identically to	wait() if pid has a value  of  -1  and
       options	has  a value of	zero.  Otherwise, the behavior of waitpid() is
       modified	by the values of pid and options as follows:

       pid specifies a set of child processes for which	status	is  requested.
       waitpid() only returns the status of a child process from this set.

	      o	 If  pid  is  equal  to	 -1, status is requested for any child
		 process.  In this repect, waitpid()  is  then	equivalent  to
		 wait().

	      o	 If pid	is greater than	zero, it specifies the process ID of a
		 single	child process for which	status is requested.

	      o	 If pid	is equal to zero, status is requested  for  any	 child
		 process  whose	process	group ID is equal to that of the call-
		 ing process.

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

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

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

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

       wait3() is an alternate interface that allows both non-blocking	status
       collection  and the collection of the status of children	stopped	by any
       means.  The status parameter is defined as above.  The options  parame-
       ter  is used to indicate	the call should	not block if there are no pro-
       cesses that have	status to report (WNOHANG), and/or  that  children  of
       the  current  process that are stopped due to a SIGTTIN,	SIGTTOU, SIGT-
       STP, or SIGSTOP signal are eligible to have their  status  reported  as
       well  (WUNTRACED).   A  terminated  child is discarded after it reports
       status, and a stopped process will not  report  its  status  more  than
       once.  If rusage	is not a NULL pointer, a summary of the	resources used
       by the terminated process and all its children is returned.  (This  in-
       formation is currently not available for	stopped	processes.)

       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 ORing the two values.

       wait4()	is  another alternate interface.  With a pid argument of 0, it
       is equivalent to	wait3().  If pid has a nonzero value, then wait4() re-
       turns  status  only for the indicated process ID, but not for any other
       child processes.

       WIFSTOPPED, WIFSIGNALED,	WIFEXITED, WEXITSTATUS,	WTERMSIG, and WSTOPSIG
       are  macros that	take an	argument status, of type `int',	as returned by
       wait(), wait3(),	or wait4().  WIFSTOPPED	evaluates to true (1) when the
       process	for which the wait() call was made is stopped, or to false (0)
       otherwise.  If WIFSTOPPED(status) is non-zero,  WSTOPSIG	 evaluates  to
       the  number  of	the  signal  that  caused  the	child process to stop.
       WIFSIGNALED evaluates to	true when the process was  terminated  with  a
       signal.	 If WIFSIGNALED(status)	is non-zero, WTERMSIG evaluates	to the
       number of the signal that caused	the termination	of the child  process.
       WIFEXITED  evaluates  to	 true  when  the  process  exited  by using an
       exit(2V)	call.  If WIFEXITED(status) is non-zero, WEXITSTATUS evaluates
       to  the low-order byte of the argument that the child process passed to
       _exit() (see exit(2V)) or exit(3), or the value the child  process  re-
       turned from main() (see execve(2V)).

       If  the	information  stored  at	the location pointed to	by statusp was
       stored there by a call to waitpid() that	specified the WUNTRACED	 flag,
       exactly	one  of	the macros WIFEXITED(*statusp),	WIFSIGNALED(*statusp),
       and WIFSTOPPED(*statusp)	will evaluate to a non-zero value.  If the in-
       formation stored	at the location	pointed	to by statusp was stored there
       by a call to waitpid() that did not specify the WUNTRACED flag or by  a
       call  to	 wait(),  exactly  one	of  the	macros WIFEXITED(*statusp) and
       WIFSIGNALED(*statusp) will evaluate to a	non-zero value.

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

RETURN VALUES
       If wait() or waitpid() 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  in-
       dicate the error.

       If  wait()  or  waitpid() return	due to the delivery of a signal	to the
       calling process,	a value	of -1 is returned and errno is set  to	EINTR.
       If  waitpid()  function 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, a value of zero is returned.  Otherwise, a	value  of  -1  is  re-
       turned, and errno is set	to indicate the	error.

       wait3()	and  wait4() 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 a	value of -1 and	set errno to indicate the  er-
       ror.

ERRORS
       wait(),	wait3(), or wait4() will fail and return immediately if	one or
       more of the following are true:

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

       EFAULT	      statusp or rusage	points to an illegal address.

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

       waitpid() may set errno to:

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

       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.

       wait(), wait3(),	and wait4() will terminate prematurely,	return -1, and
       set errno to: EINTR upon	the arrival of a signal	whose SV_INTERRUPT bit
       in its flags field is set (see sigvec(2)	and  siginterrupt(3V)).	  sig-
       nal(3V),	 in  the System	V compatibility	library, sets this bit for any
       signal it catches.

SEE ALSO
       exit(2V), fork(2V), getrusage(2), ptrace(2), sigvec(2), pause(3V), sig-
       interrupt(3V), signal(3V), times(3V)

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

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

       Previous	SunOS releases used union wait *statusp	and union wait	status
       in  place  of int *statusp and intstatus.  The union contained a	member
       w_status	that could be treated in the same way as status.

       Other members of	the wait union could be	used to	extract	this  informa-
       tion more conveniently:

	      o	 If  the  w_stopval  member  had the value WSTOPPED, the child
		 process had stopped; the value	of the	w_stopsig  member  was
		 the signal that stopped the process.

	      o	 If  the w_termsig member was non-zero,	the child process ter-
		 minated due to	a signal; the value of	the  w_termsig	member
		 was the number	of the signal that terminated the process.  If
		 the w_coredump	member was non-zero, a core dump was produced.

	      o	 Otherwise, the	child process terminated  due  to  a  call  to
		 exit().   The value of	the w_retcode member was the low-order
		 8 bits	of the argument	 that  the  child  process  passed  to
		 exit().

       union  wait  is obsolete	in light of the	new specifications provided by
       IEEE Std	1003.1-1988 and	endorsed by SVID89 and	XPG3.	SunOS  Release
       4.1  supports union wait	for backward compatibility, but	it will	disap-
       pear in a future	release.

				21 January 1990			      WAIT(2V)

NAME | SYNOPSIS | SYSTEM V SYNOPSIS | DESCRIPTION | RETURN VALUES | ERRORS | SEE ALSO | NOTES

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

home | help