HPlogo HP-UX Reference Volume 3 of 5 > w

wait(2)
» 

Technical documentation

Complete book in PDF

 » Table of Contents

 » Index

spacerspacerspacer
spacer
spacer
  		 
 

NAME

wait, waitpid — wait for child process to stop or terminate

SYNOPSIS

#include <sys/types.h> OH #include <sys/wait.h> pid_t wait(int *stat_loc); pid_t waitpid(pid_t pid, int *stat_loc, int options);

DESCRIPTION

The wait() and waitpid() functions allow the calling process to obtain status information pertaining to one of its child processes. Various 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 will suspend 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 will be immediate.

The waitpid() function will behave identically to wait(), if the pid argument is (pid_t)-1 and the options argument is 0. Otherwise, its behaviour will be modified by the values of the pid and options arguments.

The pid argument specifies a set of child processes for which status is requested. The waitpid() function will only return the status of a child process from this set:

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

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

  • If pid is 0, status is requested for any child process whose process group ID is equal to that of the calling process.

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

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

WCONTINUED

The waitpid() function will report the status of any continued child process specified by pid whose status has not been reported since it continued from a job control stop.

WNOHANG

The waitpid() function will 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, will also be reported to the requesting process.

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

If wait() or waitpid() return because the status of a child process is available, these functions will return a value equal to the process ID of the child process. In this case, if the value of the argument stat_loc is not a null pointer, information will be stored in the location pointed to by stat_loc. If and only if the status returned is from a terminated child process that returned 0 from main() or passed 0 as the status argument to _exit() or exit(), the value stored at the location pointed to by stat_loc will be 0. Regardless of its value, this information may be interpreted using the following macros, which are defined in <sys/wait.h> and evaluate to integral expressions; the stat_val argument is the integer value pointed to by stat_loc.

WIFEXITED(stat_val)

Evaluates to a non-zero value if status was returned for a child process that terminated normally.

WEXITSTATUS(stat_val)

If the value of WIFEXITED(stat_val) is non-zero, this macro evaluates to the low-order 8 bits of the status argument that the child process passed to _exit() or exit(), or the value the child process returned from main().

WIFSIGNALED(stat_val)

Evaluates to non-zero value if status was returned for a child process that terminated due to the receipt of a signal that was not caught (see <signal.h>).

WTERMSIG(stat_val)

If the value of WIFSIGNALED(stat_val) is non-zero, this macro evaluates to the number of the signal that caused the termination of the child process.

WIFSTOPPED(stat_val)

Evaluates to a non-zero value if status was returned for a child process that is currently stopped.

WSTOPSIG(stat_val)

If the value of WIFSTOPPED(stat_val) is non-zero, this macro evaluates to the number of the signal that caused the child process to stop.

WIFCONTINUED(stat_val)

Evaluates to a non-zero value if status was returned for a child process that has continued from a job control stop.

If the information pointed to by stat_loc was stored by a call to waitpid() that specified the WUNTRACED flag and did not specify the WCONTINUED flag, exactly one of the macros WIFEXITED(*stat_loc), WIFSIGNALED(*stat_loc), and WIFSTOPPED(*stat_loc) will evaluate to a non-zero value.

If the information pointed to by stat_loc was stored by a call to waitpid() that specified the WUNTRACED and WCONTINUED flags, exactly one of the macros WIFEXITED(*stat_loc), WIFSIGNALED(*stat_loc), WIFSTOPPED(*stat_loc), and WIFCONTINUED (*stat_loc) will evaluate to a non-zero value.

If the information pointed to by stat_loc was stored by a call to waitpid() that did not specify the WUNTRACED or WCONTINUED flags, or by a call to the wait() function, exactly one of the macros WIFEXITED(*stat_loc) and WIFSIGNALED(*stat_loc) will evaluate to a non-zero value.

If the information pointed to by stat_loc was stored by a call to waitpid() that did not specify the WUNTRACED flag and specified the WCONTINUED flag, by a call to the wait() function, exactly one of the macros WIFEXITED(*stat_loc), WIFSIGNALED(*stat_loc), and WIFCONTINUED(*stat_loc) will evaluate to a non-zero value.

There may be additional implementation-dependent circumstances under which wait() or waitpid() report status. This will not occur unless the calling process or one of its child processes explicitly makes use of a non-standard extension. In these cases the interpretation of the reported status is implementation-dependent.

If a parent process terminates without waiting for all of its child processes to terminate, the remaining child processes will be assigned a new parent process ID corresponding to an implementation-dependent system process.

RETURN VALUE

If wait() or waitpid() returns because the status of a child process is available, these functions will return a value equal to the process ID of the child process for which status is reported. If wait() or waitpid() returns due to the delivery of a signal to the calling process, -1 will be returned and errno will be set to EINTR. If waitpid() 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, 0 will be returned. Otherwise, (pid_t)-1 will be returned, and errno will be set to indicate the error.

ERRORS

The wait() function will fail if:

[ECHILD]

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

[EINTR]

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

The waitpid() function will fail if:

[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 stat_loc is undefined.

[EINVAL]

The options argument is not valid.

APPLICATION USAGE

Threads Considerations

In a multi-threaded application, only the calling thread is suspended by wait() or waitpid().

wait() and waitpid() will not return until all threads in the process have reached the desired state. For example, wait() and waitpid() will not return until all threads have terminated. If the WUNTRACED or WCONTINUED options are specified for waitpid(), the function will not return until all threads have stopped or continued respectively.

SEE ALSO

exec(2), exit(2), fork(2), wait3(2), waitid(2), <sys/types.h>, <sys/wait.h>.

CHANGE HISTORY

First released in Issue 1.

Derived from Issue 1 of the SVID.

Issue 4

The following change is incorporated for alignment with the ISO POSIX-1 standard:

  • Text describing conditions under which 0 will be returned when WNOHANG is set in options is added to the RETURN VALUE section.

Other changes are incorporated as follows:

  • The header <sys/types.h> is now marked as optional (OH); this header need not be included on XSI-conformant systems.

  • Error return values throughout the DESCRIPTION and RETURN VALUE sections are changed to show the proper casting (that is, (pid_t)-1.

  • The words "If the implementation supports job control" are removed from the description of WUNTRACED. This is because job control is defined as mandatory for Issue 4 conforming implementations.

Issue 4, Version 2

The following changes are incorporated in the DESCRIPTION for X/OPEN UNIX conformance:

  • The WCONTINUED options flag and the WIFCONTINUED(stat_val) macro are added.

  • Text following the list of options flags explains the implications of setting the SA_NOCLDWAIT signal flag, or setting SIGCHILD to SIG_IGN.

  • Text following the list of macros, which explains what macros return non-zero values in certain cases, is expanded and the value of the WCONTINUED flag on the previous call to waitpid() is taken into account.

wait HP-UX EXTENSIONS

NAME (HP-UX)

wait(), waitpid() - wait for child or traced process to stop or terminate

DESCRIPTION

wait()

If a parent process terminates without waiting for its child processes to terminate, the parent process ID of each child process is set to 1. This means the initialization process inherits the child processes.

WCOREDUMP(*stat_loc)

If the value of WIFSIGNALED(*stat_loc) is nonzero, this macro evaluates to a nonzero value if a "core image" was produced (see signal(5)).

waitpid()

WNOWAIT

Keep the process whose status is returned in *stat_loc in a waitable state. The process may be waited for again with identical results, provided the state of the process doesn't change in the interim.

WUNTRACED

If and only if this flag is set, waitpid() or wait3() returns information on child or attached processes that are stopped but not traced (with ptrace()) because they received a SIGTTIN, SIGTTOU, SIGTSTP, or SIGSTOP signal, and whose status has not yet been reported. Regardless of this flag, status is returned for child or attached processes that have terminated or are stopped and traced and whose status has not yet been reported.

Notes

Earlier HP-UX versions documented the bit encodings of the status returned by wait() rather than the macros WCOREDUMP, WEXITSTATUS, WIFEXITED, WIFSIGNALED, WIFSTOPPED, WSTOPSIG, and WTERMSIG. Applications using those bit encodings will continue to work correctly. However, new applications should use the macros for maximum portability.

In earlier HP-UX versions, the macros WIFEXITED, WIFSIGNALED, and WIFSTOPPED have the same definitions as the correspondingly named macros in the BSD 4.3 and earlier systems. Existing applications that depend on these definitions will continue to work correctly. However, if the application is recompiled, the feature test macro _BSD must be turned on for the compilation so that the old definitions of these macros are obtained. New definitions of these macros are in effect by default. The only difference between the old and new definitions is the type of the argument. Type union wait is used in the BSD definitions while type int is used in the default definitions.

ERRORS

If wait() or waitpid() fails, errno is set to one of the following values.

[EACCES]

The calling process of waitpid() does not have read permission to the pid.

[EFAULT]

stat_loc points to an illegal address. The reliable detection of this error is implementation-dependent.

WARNINGS

The behavior of wait() and waitpid() is affected if the SIGCLD signal is set to SIG_IGN. See the WARNINGS section of signal(5). Signal handlers that cause system calls to be restarted can affect the EINTR condition described above (see bsdproc(3C), sigaction(2), and sigvector(2)).

AUTHOR

wait(), waitpid(), and wait3() were developed by HP, AT&T, and the University of California, Berkeley.

SEE ALSO

Exit conditions ($?) in sh(1); exec(2), exit(2), fork(2), pause(2), ptrace(2), signal(5).

STANDARDS CONFORMANCE

wait(): AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1

waitpid(): AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1



w
  		 


wait3  
© Hewlett-Packard Development Company, L.P.