wait(2) 							System Calls Manual							   wait(2)

NAME

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

SYNOPSIS

       #include <sys/wait.h>

       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 <sys/resource.h>

       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 <sys/types.h> before the one for <sys/wait.h> 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 industry standards and associated tags.

PARAMETERS

       Points  to  a location that contains the termination status of the child process as defined in the <sys/wait.h> header file.  Specifies the
       child process or set of child processes.  Modifies the behavior of the function. The flags for the options parameter  are  defined  in  the
       DESCRIPTION  section.  Specifies the location of a structure that will contain the resource usage information for child processes that have
       terminated.

DESCRIPTION

       The wait(), waitpid(), and wait3() functions allow the calling process to obtain status information pertaining to one  of  its  child  pro-
       cesses.	 Various options permit status information to be obtained for child processes that have terminated or stopped.	If status informa-
       tion 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  avail-
       able,  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 speci-
       fies a value of zero (0).  Should these parameters contain other values, the waitpid() function is changed as specified by those values.

       The  wait3()  function  is similar to waitpid() in allowing the calling process to obtain status information for specified child processes.
       The wait3() function also includes a resource_usage parameter.  If this parameter 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
       parameter.  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()  func-
       tion.   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: [XPG4-UNIX]  Specifies report-
       ing 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.  [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.  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.  Specifies that
       the call return additional information when the child process is stopped because it received a SIGTTIN, SIGTTOU, SIGSTOP, or SIGTSTOP  sig-
       nal.

       [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 <sys/wait.h> header file that evaluate to integral
       expressions.  In the following macro descriptions, the status_value parameter is equal to the integer value pointed to by the  status_loca-
       tion  parameter:  Evaluates to a nonzero value if status was returned for a child process that terminated normally.  If the value of WIFEX-
       ITED(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.  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.	 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.  Evaluates to a nonzero value
       if status was returned for a child process that is currently stopped.  If the value of  WIFSTOPPED(status_value)  is  nonzero,  this  macro
       evaluates  to  the  number  of  the signal that caused the child process to stop.  [XPG4-UNIX]  Evaluates to a non-zero value if status was
       returned for a child process that has continued from a job control stop.

       [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) WIFSIG-
       NALED(*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 WCONTIN-
       UED flags, one of the following macros  evaluates  to  a  nonzero  value:  WIFEXITED(*status_location)  WIFSIGNALED(*status_location)  WIF-
       STOPPED(*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 speci-
       fied the WCONTINUED flag, or by a call to wait(), one of the following macros evaluates 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: The  calling  process
       has  no	existing  unwaited-for child processes.  The function was terminated by receipt of a signal.  [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: The process or process group ID specified by the process_id  parame-
       ter 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: The value of the options parameter is not valid.

RELATED INFORMATION

       Functions: exec(2), exit(2), fork(2), ptrace(2), getrusage(2), sigaction(2), pause(3)

       Standards: standards(5) delim off

																	   wait(2)