wait3(), wait4() -- wait for process to terminate or stop

SYNOPSIS

#include <sys/wait.h>

#include <sys/time.h>

#include <sys/resource.h>

pid_t wait3(int *stat_loc, int options, struct rusage *rusage);

pid_t wait4(pid_t pid, int *stat_loc, int options, struct rusage *rusage);

The wait3() 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 already been reported, return is immediate, returning the process ID and status of one of those children. If that child process has died, it is discarded. If there are no children, -1 is returned immediately. If there are only running or stopped but reported children, the calling process is blocked.

The wait4() function is an extended 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. The status can be evaluated using the macros listed on the wstat() reference page.

PARAMETERS

pid

Specifies a set of child processes for which the status is requested:

If pid is equal to -1, status is requested for any child process. In this respect, wait4() is 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. This setting is not currently supported.

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. This setting is not currently supported.

options

Is the bitwise inclusive-OR of zero or more of the following flags, defined in <sys/wait.h>:

WNOHANG: Execution of the calling process is not suspended if status is not immediately available for any child process.
WUNTRACED: The status of any child processes that are stopped, and whose status has not yet been reported since they stopped, are also reported to the requesting process.

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 the bitwise OR operation of the two values.

stat_loc

Specifies the location where the child process' exit status is stored. If NULL is passed, no exit status is returned. Otherwise, the following macros defined in <sys/wait.h> can be used to evaluate the returned status:

WIFEXITED(s): Evaluates to a non-zero value if status was returned for a child process that exited normally.
WEXITSTATUS(s): If the value of WIFEXITED(s) 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(s): Evaluates to a non-zero value if status was returned for a child process that terminated due to receipt of a signal that was not caught.
WTERMSIG(s): If the value of WIFSIGNALED(s) is non-zero, this macro evaluates to the number of the signal that caused the termination of the child process.
WIFCORED(s): Evaluates to a non-zero value if status was returned for a child process that terminated due to receipt of a signal that was not caught, and whose default action is to dump core.
WCOREDUMP(s): Evaluates to a non-zero value if status was returned for a child process that terminated due to receipt of a signal that was not caught, and whose default action is to dump core.
WCORESIG(s): If the value of WIFCORED(s) is non-zero, this macro evaluates to the number of the signal that caused the termination of the child process.
WIFSTOPPED(s): Evaluates to a non-zero value if status was returned for a child process that is currently stopped.
WSTOPSIG(s): If the value of WIFSTOPPED(s) is non-zero, this macro evaluates to the number of the signal that caused the child process to stop.

rusage

Specifies the location where a summary of the resources used by the terminated process and all of its children is returned. Only the user time used and the system time used is currently available. They are returned in the ru_utime and ru_stime members of the rusage structure respectively. If NULL is passed, then no resource usage is returned.

RETURN VALUES

If wait3() or wait4() returns due to a stopped or terminated child process, the process ID of the child is returned to the calling process. Otherwise, -1 is returned and errno is set to indicate the error.

If wait3() or wait4() return due to the delivery of a signal to the calling process, -1 is returned and errno is set to EINTR. If WNOHANG was 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 is returned. Otherwise, -1 is returned and errno is set to indicate the error.

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

ERRORS

The wait3() and wait4() functions will fail and return immediately if:

ECHILD: The calling process has no existing unwaited-for child processes.
EFAULT: The stat_loc or rusage arguments point to an illegal address.
EINTR: The function was interrupted by a signal. The value of the location pointed to by stat_loc is undefined.
EINVAL: The value of options is not valid.

The wait4() function may fail if:

ECHILD: The process specified by pid does not exist or is not a child of the calling process.

The wait3()and wait4() functions will terminate prematurely, return -1, and set errno to EINTR upon the arrival of a signal whose SA_RESTART bit in its flags field is not set (see the sigaction() reference page).

NOTES

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

The wait3() and wait4() functions are automatically restarted when a process receives a signal while awaiting termination of a child process, unless the SA_RESTART bit is not set in the flags for that signal.

CONFORMANCE

BSD 4.4.

MULTITHREAD SAFETY LEVEL

Async-signals-safe.

PORTING ISSUES

The NuTCRACKER Platform converts the exit status of native Windows applications to UNIX format, which allows wait3() and wait4() to work correctly with either NuTCRACKER Platform or non-NuTCRACKER Platform processes.

The CPU usage time returned is only that of the child and does not include the time spent by the grand-child.

The process ID passed to wait4() should be one returned by a function in the PTC MKS Toolkit UNIX APIs. Refer to Process Identification in the Windows Concepts chapter of the PTC MKS Toolkit UNIX to Windows Porting Guide.

AVAILABILITY

PTC MKS Toolkit for Professional Developers
PTC MKS Toolkit for Professional Developers 64-Bit Edition
PTC MKS Toolkit for Enterprise Developers
PTC MKS Toolkit for Enterprise Developers 64-Bit Edition

wait3(), wait4()
wait for process to terminate or stop

Function