HP 3000 Manuals HP 3000 Manuals
waitpid
Suspends the calling process to wait for exit status of the specified
child processes.
Syntax
#include <sys/types.h>
#include <sys/wait.h>
pid_t waitpid (pid_t pid, int *stat_loc, int options);
Parameters
pid An parameter of type pid_t that specifies the process whose
status is being reported. Following are valid values and
their meanings:
>0 A single child process with process ID equal to pid.
0 All child processes with process group ID equal to the
caller's.
-1 All child processes.
<-1 All child processes with process group ID equal to the
absolute value of pid.
stat_loc A pointer to the exit status of the child process. No
information is stored if stat_loc is NULL.
options Modifies the behavior of the waitpid() function. The contents
of options is a bitwise inclusive OR of the following flags
(defined in <sys/wait.h>):
WNOHANG Do not suspend the calling process when no child
status is available.
WHANG Suspend and wait for a child status if none is yet
available.
WUNTRACED Suspend and wait for the status of a stopped child
process.
Return Values
>0 Success. The process ID of a terminated child process whose
process ID matches pid is returned.
0 The WNOHANG option is specified in options and no child
specified by pid has terminated.
-1 An error occurred. There is no result, and errno is set to
indicate the error condition.
Description
The waitpid() function suspends the calling process until status
information for the specified child process(es) is available. If status
information is already available, wait() returns immediately.
If the calling process receives a signal whose action is to terminate,
the calling process terminates. If the calling process receives a signal
whose action is to execute a signal handling function, waitpid() returns
to the calling process.
If status is available for more than one specified process, the order in
which their status is reported may not correspond to the order of their
termination.
The waitpid() function is identical to the wait() function when the pid
parameter has a value of -1 and options is equal to zero.
The waitpid() function returns to the argument pointed to by stat_loc an
exit status of 0 if, and only if, the child process that returned status
took one of the following two actions:
* returned a value of zero from its main() function (outer block)
* passed a status value of zero to _exit() or exit()
The following macros that evaluate the stat_loc parameter, regardless of
its value, are defined in the header <sys/wait.h>:
WIFEXITED(exit_status) Evaluates to a nonzero value if status was
returned for a child process that terminated
normally.
WEXITSTATUS(exit_status) If WIFEXITED is nonzero, this macro evaluates
to the low-order 8 bits of the stat_loc
parameter that the child process passed to
_exit() or exit(), or the value that the child
process returned from main().
WIFSIGNALED(exit_status) Evaluates to a nonzero value if status was
returned for a child process that terminated
due to the receipt of a signal that was not
caught.
WTERMSIG(exit_status) If WIFSIGNALED is nonzero, this macro evaluates
to the number of the signal that caused the
termination of the child process.
WIFSTOPPED(exit_status) Evaluates to a nonzero value if status was
returned for a child process that is currently
stopped.
WSTOPSIG(exit_status) If WIFSTOPPED is nonzero, this macro evaluates
to the number of the signal that caused the
child process to stop.
Implementation Considerations
Refer to the EFAULT error description below.
If a parent process terminates without waiting for all of its child
processes to terminate, the remaining child processes are terminated.
Errors
If an error occurs, errno is set to one of the following values:
ECHILD CAUSE The process or process group specified by pid does
not exist or is not a child of the calling process.
ACTION No action is necessary.
EFAULT CAUSE The system detected a bad address in attempting to
use the stat_loc parameter.
ACTION Make sure that the pointer is correctly initialized.
EINTR CAUSE The function was interrupted by a signal. The
stat_loc parameter's value is undefined.
ACTION Call the waitpid() function again to continue
waiting.
EINVAL CAUSE The options parameter is invalid.
ACTION Specify a valid option as defined in the file
<wait.h>.
See Also
_exit(), fork(), pause(), wait(), <signal.h>, POSIX.1 (Section 3.2.1)