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(3UCB)	   SunOS/BSD Compatibility Library Functions	    wait(3UCB)

NAME
       wait,  wait3, wait4, waitpid, WIFSTOPPED, WIFSIGNALED, WIFEXITED	- wait
       for process to terminate	or stop

SYNOPSIS
       /usr/ucb/cc [ flag ... ]	file ...
       #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;

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 process has
       died or stopped due to tracing and this has  not	 been  reported	 using
       wait(),	return	is immediate, returning	the process ID and exit	status
       of one of those children. If that child process has died,  it  is  dis-
       carded. 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  status  is  not  a  NULL  pointer, then on return from a successful
       wait() call the status of the child process whose  process  ID  is  the
       return value of wait() is stored	in the wait() union pointed to by sta-
       tus. The	w_status member	of that	union is  an  int;  it	indicates  the
       cause of	termination and	other information about	the terminated process
       in the following	manner:

	  o  If	the low-order 8	bits of	w_status are equal to 0177, the	 child
	     process  has  stopped;  the 8 bits	higher up from the low-order 8
	     bits of w_status contain the number of the	signal that caused the
	     process to	stop. See ptrace(2) and	sigvec(3UCB).

	  o  If	 the  low-order	 8  bits  of w_status are non-zero and are not
	     equal to 0177, the	child process terminated due to	a signal;  the
	     low-order	7  bits	 of  w_status contain the number of the	signal
	     that terminated the process. In addition, if the  low-order  sev-
	     enth bit of w_status (that	is, bit	0200) is set, a	``core image''
	     of	the process was	produced; see sigvec(3UCB).

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

       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 respect, 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  calling
	     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 pro-
	     cesses 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  parameter
       is used to indicate the call should not block if	there are no processes
       that have status	to report (WNOHANG), and/or that children of the  cur-
       rent  process  that  are	stopped	due to a SIGTTIN, SIGTTOU, SIGTSTP, or
       SIGSTOP signal are eligible to have their status	reported as well (WUN-
       TRACED).	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. Only the user time  used  and
       the  system  time  used	are  currently available. They are returned in
       rusage.ru_utime and rusage.ru_stime, 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 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()
       returns status only for the indicated process ID, but not for any other
       child processes.

       WIFSTOPPED,  WIFSIGNALED,  WIFEXITED,  are macros that take an argument
       status, of type int, as returned	by wait(), or  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. WIFSIGNALED	evalu-
       ates  to	 true when the process was terminated with a signal. WIFEXITED
       evaluates to true when the process exited by using an exit(2) call.

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 indi-
       cate 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 returned,
       and errno is set	to indicate the	error.

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

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
	     The status	or rusage arguments point to an	illegal	address.

       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	 loca-
	     tion pointed to by	statusp	is undefined.

       EINVAL
	     The value of options is not valid.

       wait(), and 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(3UCB)	and  siginter-
       rupt(3UCB)). signal(3UCB), sets this bit	for any	signal it catches.

SEE ALSO
       exit(2),	 ptrace(2),  wait(2),  waitpid(2),  getrusage(3C),   siginter-
       rupt(3UCB), signal(3UCB), sigvec(3UCB), signal(3C)

NOTES
       Use of these interfaces should be restricted to only applications writ-
       ten on BSD platforms.  Use of these interfaces with any of  the	system
       libraries or in multi-thread applications is unsupported.

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

       wait(), and 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  sig-
       nal.

       Calls  to wait()	with an	argument of  0 should be cast to type `int *',
       as in:

       wait((int *)0)

       Previous	SunOS releases used union wait*statusp and union  wait	status
       in  place  of int *statusp and int status. 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	termi-
	     nated due to a signal; the	value of the w_termsig member was  the
	     number of the signal that terminated the process.	If the w_core-
	     dump 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	unionwait for backward compatibility, but it will disappear in
       a future	release.

SunOS 5.9			  5 Mar	1993			    wait(3UCB)

NAME | 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=3ucb&manpath=SunOS+5.9>

home | help