unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (OSF1-V5.1-alpha)
Page:
Section:
Apropos / Subsearch:
optional field



wait(2)								      wait(2)



NAME

  wait,	waitpid, wait3,	wait4 -	Waits for a child process to stop or ter-
  minate

SYNOPSIS

  #include <&lt;sys/wait.h>&gt;

  pid_t	wait(
	  int *status_location);

  pid_t	waitpid(
	  pid_t	process_id,
	  int *status_location,
	  int options);

  pid_t	wait3(
	  int *status_location,
	  int options,
	  struct rusage	*resource_usage);

  The following	function declarations do not conform to	current	standards and
  are supported	only for backward compatibility:

  #include <&lt;sys/resource.h>&gt;

  pid_t	wait3(
	  union	wait *status_location,
	  int options,
	  struct rusage	*resource_usage);

  pid_t	wait4(
	  pid_t	process_id,
	  union	wait *status_location,
	  int options,
	  struct rusage	*resource_usage);

  Application developers may want to specify an	#include statement for
  <&lt;sys/types.h>&gt;	before the one for <&lt;sys/wait.h>&gt;	if programs are	being
  developed for	multiple platforms. The	additional #include statement is not
  required on Tru64 UNIX systems or by ISO or X/Open standards,	but may	be
  required on other vendors' systems that conform to these standards.

  See the NOTES	section	for further information	on the backward-compatible
  versions of wait3() and wait4().

STANDARDS

  Interfaces documented	on this	reference page conform to industry standards
  as follows:


  wait(), waitpid(), wait3(): XSH4.2

  Refer	to the standards(5) reference page for more information	about indus-
  try standards	and associated tags.


PARAMETERS

  status_location
	    Points to a	location that contains the termination status of the
	    child process as defined in	the <&lt;sys/wait.h>&gt; header	file.

  process_id
	    Specifies the child	process	or set of child	processes.

  options   Modifies the behavior of the function. The flags for the options
	    parameter are defined in the DESCRIPTION section.

  resource_usage
	    Specifies the location of a	structure that will contain the
	    resource usage information for child processes that	have ter-
	    minated.

DESCRIPTION

  The wait(), waitpid(), and wait3() functions allow the calling process to
  obtain status	information pertaining to one of its child processes.  Vari-
  ous options permit status information	to be obtained for child processes
  that have terminated or stopped.  If status information is available for
  two or more child processes, the order in which their	status is reported is
  unspecified.

  The wait() function suspends execution of the	calling	process	until status
  information for one of its terminated	child processes	is available, or
  until	delivery of a signal whose action is either to execute a signal-
  catching function or to terminate the	process.  If status information	is
  available prior to the call to wait(), return	is immediate.

  The effect of	the wait() function can	be modified by setting the SIGCHLD
  signal.  See the sigaction(2)	reference page for more	information.

  The waitpid()	function behaves identically to	wait(),	if the process_id
  parameter has	a value	of (pid_t)-1 and the options parameter specifies a
  value	of zero	(0).  Should these parameters contain other values, the	wait-
  pid()	function is changed as specified by those values.

  The wait3() function is similar to waitpid() in allowing the calling pro-
  cess to obtain status	information for	specified child	processes. The
  wait3() function also	includes a resource_usage parameter.  If this parame-
  ter is not a null pointer, the struct	rusage structure pointed to by the
  third	argument is filled in for the child process identified by the return
  value.

  [Tru64 UNIX]	The wait4() function is	similar	to wait3(), except that
  wait4() waits	for a specific child as	indicated by the process_id parame-
  ter.	A program that calls wait4() must be compiled with the _BSD switch
  defined.  See	the NOTES section for further information.

  In a multithreaded environment, the wait(), waitpid(), wait3(), and wait4()
  functions block only the calling thread.

  The process_id parameter allows the calling process to gather	status from a
  specific set of child	processes.  The	waitpid() and wait4() functions
  return the status only of child processes from this set.  The	following
  rules	define the set:

    +  If the process_id parameter is equal to (pid_t)-1, status is requested
       for any child process.  In this respect,	the waitpid() function is
       equivalent to the wait()	function.

    +  If the process_id parameter is greater than zero	(0), it	specifies the
       process ID of a single child process for	which status is	requested.

    +  If the process_id parameter is equal to zero (0), status	is requested
       for any child process whose process group ID is equal to	that of	the
       calling process.

    +  If the process_id parameter is less than	(pid_t)-1, status is
       requested for any child process whose process group ID is equal to the
       absolute	value of the process_id	parameter.

  The options parameter	to the waitpid(), wait3(), and wait4() functions
  modifies the behavior	of the function.  The flags for	the options parameter
  can be combined by specifying	them in	a bitwise-inclusive OR operation.
  The flags are	as follows:

  WCONTINUED
	    [XPG4-UNIX]	 Specifies reporting the status	of any child process
	    identified by the process_id parameter whose status	has not	been
	    reported since it continued	from a job control stop.

  WNOWAIT   [Tru64 UNIX]  Specifies that the process whose status is returned
	    in status_location will be kept in a waitable state.  The process
	    can	be waited for again with the same results.

  WNOHANG   Prevents the calling process from being suspended.	If there are
	    child processes that have been stopped or terminated, one is
	    chosen and waitpid() returns its pid, just as when the WNOHANGn
	    flag is not	specified.  If there are no such processes (that is,
	    if conditions are such that	waitpid() without the WNOHANG flag
	    would have suspended the calling process), zero (0)	is returned.
	    Because you	can never wait for process 0, there is no confusion
	    arising from this return.

  WUNTRACED Specifies that the call return additional information when the
	    child process is stopped because it	received a SIGTTIN, SIGTTOU,
	    SIGSTOP, or	SIGTSTOP signal.

  [XPG4-UNIX]  If the calling process has SA_NOCLDWAIT set or has SIGCHLD set
  to SIG_IGN, and the process has no unwaited-for child	processes that were
  transformed into zombie processes, it	will block until all of	its child
  processes terminate, and wait() and waitpid()	will fail and set errno	to
  [ECHILD].

  If the wait(), waitpid(), wait3(), or	wait4()	functions return because the
  status of a child process is available, the process ID of the	child process
  is returned.	In this	instance, information is stored	in the location
  pointed to by	the status_location parameter if the value of the
  status_location is not null.	The value stored in the	location pointed to
  by the status_location parameter is zero (0) if, and only if,	the status is
  returned from	a terminated child process that	did one	of the following:

    +  Returned	zero (0) from the main() routine.

    +  Passed zero (0) as the status parameter to the _exit or exit function.

  Regardless of	its value, this	information can	be defined using the macros
  defined in the <&lt;sys/wait.h>&gt; header file that evaluate	to integral expres-
  sions.  In the following macro descriptions, the status_value	parameter is
  equal	to the integer value pointed to	by the status_location parameter:

  WIFEXITED(status_value)
	    Evaluates to a nonzero value if status was returned	for a child
	    process that terminated normally.

  WEXITSTATUS(status_value)
	    If the value of WIFEXITED(status_value) is nonzero,	this macro
	    evaluates to the low-order 8 bits of the status parameter that
	    the	child process passed to	the _exit or exit function, or the
	    value the child process returned from the main() routine.

  WIFSIGNALED(status_value)
	    Evaluates to nonzero value if status was returned for a child
	    process that terminated due	to the receipt of a signal that	was
	    not	caught.

  WTERMSIG(status_value)
	    If the value of WIFSIGNALED(status_value) is nonzero, this macro
	    evaluates to the number of the signal that caused the termination
	    of the child process.

  WIFSTOPPED(status_value)
	    Evaluates to a nonzero value if status was returned	for a child
	    process that is currently stopped.

  WSTOPSIG(status_value)
	    If the value of WIFSTOPPED(status_value) is	nonzero, this macro
	    evaluates to the number of the signal that caused the child	pro-
	    cess to stop.

  WIFCONTINUED(status_value)
	    [XPG4-UNIX]	 Evaluates to a	non-zero value if status was returned
	    for	a child	process	that has continued from	a job control stop.

				     Note

       [Tru64 UNIX]  The following behavior described for waitpid() and
       wait3() also applies to the libbsd versions of wait3() and
       wait4(),	except the parameter to	the macros should be the
       w_status	member of the union pointed to by the status_location
       parameter.


  If the information pointed to	by the status_location parameter was stored
  by a call to waitpid() or wait3() that specified the WUNTRACED flag and did
  not specify the WCONTINUED flag, one of the following	macros evaluates to a
  nonzero value:

    +  WIFEXITED(*status_location)

    +  WIFSIGNALED(*status_location)

    +  WIFSTOPPED(*status_location)

  If the information pointed to	by status_location was stored by a call	to
  waitpid() or wait3() that specified both the WUNTRACED and WCONTINUED
  flags, one of	the following macros evaluates to a nonzero value:

    +  WIFEXITED(*status_location)

    +  WIFSIGNALED(*status_location)

    +  WIFSTOPPED(*status_location)

    +  WIFCONTINUED(*status_location)

  If the information pointed to	by status_location was stored by a call	to
  waitpid() or wait3() that specified neither the WUNTRACED nor	the
  WCONTINUED flag, or by a call	to the wait() function,	one of the following
  macros evaluates to a	nonzero	value:

    +  WIFEXITED(*status_location)

    +  WIFSIGNALED(*status_location)

  If the information pointed to	by status_location was stored by a call	to
  waitpid() or wait3() that did	not specify the	WUNTRACED and specified	the
  WCONTINUED flag, or by a call	to wait(), one of the following	macros evalu-
  ates to a nonzero value:

    +  WIFEXITED(*status_location)

    +  WIFSIGNALED(*status_location)

    +  WIFCONTINUED(*status_location)

  If a parent process terminates without waiting for all of its	child
  processes to terminate, the remaining	child processes	will be	assigned a
  parent process ID equal to the process ID of the init	process.

NOTES

  [Tru64 UNIX]	Compiling with the _BSD	switch defined and then	linking	with
  the libbsd compatibility library redefines the status_location parameter as
  the type union wait *	instead	of int *.  Programs using the backward-
  compatible versions of wait3() and wait4() functions must be compiled	in
  this manner.

RETURN VALUES

  If the wait(), waitpid(), wait3(), or	wait4()	function returns because the
  status of a child process is available, the process ID of the	child is
  returned to the calling process. If they return because a signal was caught
  by the calling process, -1 is	returned and errno is set to [EINTR].

  If the waitpid(), wait3(), or	wait4()	function was invoked with the WNOHANG
  option specified, 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 0 (zero)	is returned.  Otherwise, (pid_t-1) is
  returned, and	errno is set to	indicate the error.

ERRORS

  The wait(), waitpid(), wait3(), and wait4() functions	set errno to the
  specified values for the following conditions:

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

  [EINTR]   The	function was terminated	by receipt of a	signal.

  [EFAULT]  [Tru64 UNIX]  The status_location or resource_usage	parameter
	    points to a	location outside of the	address	space of the process.

  The waitpid()	function fails if one or both of the following are true:

  [ECHILD]  The	process	or process group ID specified by the process_id
	    parameter does not exist or	is not a child process of the calling
	    process.

  The waitpid(), wait3(), or wait4() functions fail if the following is	true:

  [EINVAL]  The	value of the options parameter is not valid.


RELATED	INFORMATION

  Functions: exec(2), exit(2), fork(2),	ptrace(2), getrusage(2), sigac-
  tion(2), pause(3)


  Standards: standards(5)