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

FreeBSD Manual Pages

  
 
  

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
       The wait() 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  been  re-
       ported  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 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  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 re-
       turn  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. Seeptrace(3C) 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-or-
	    der	 7 bits	of w_status contain the	number of the signal that ter-
	    minated the	process. In addition, if the low-order seventh 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 contain 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 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 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	termi-
       nated 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()  re-
       turns  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  ad-
		       dress.

       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(), 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),	 getrusage(3C),	 ptrace(3C),  siginterrupt(3UCB),  signal(3C),
       signal(3UCB), sigvec(3UCB), wait(3C), waitpid(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.

       The wait(), wait3(), and	wait4()	functions 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 terminated
	    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 mem-
	    ber	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.10			  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.10>

home | help