gtpc2m9i | C/C++ Language Support User's Guide |
This function allows the calling process to obtain the exit status
information from a child process.
Options permit the caller to either suspend execution of the calling
process until a child process ends or return immediately.
Format
#include <sys/wait.h>
pid_t waitpid(pid_t pid, int *stat_loc,
int options);
- pid
- A set of child processes for which status is requested. Only one
status is returned per waitpid function call.
- If pid is equal to -1, status is requested for any child
process. If status information is available for two or more processes,
the order in which their status is reported is not specified.
- If pid is greater than 0, status is requested for a single
process.
- If pid is equal to 0, status is requested for any process whose
process group ID (GID) matches the process group ID of the caller.
- If pid is less than -1, status is requested for any
process whose process group ID is equal to the absolute value of
pid.
- stat_loc
- A pointer to an integer where the wait function will return the
status of the child process. If the waitpid function returns
because a process has exited, the return value is equal to the pid
of the exiting process. For this, if the value of stat_loc
is not NULL, information is stored in the location pointed to by
stat_loc. If status is returned from a terminated child
process that returned a value of 0, the value stored at the location pointed
to by stat_loc is 0. If the return is greater than 0, you
can evaluate this information using the following macros:
WEXITSTATUS
WIFEXITED
WIFSIGNALED
WTERMSIG.
- options
- 0 or the following flag:
- WNOHANG
- The waitpid function does not suspend the calling process if
status is not immediately available for any process specified by the
pid parameter.
Normal Return
The normal return is one of the following:
- If the status of a process is available, the return code is set to the
pid of the process for which status is available.
- If WNOHANG is specified and there are valid processes to report
on, but there is no status available, a value of 0 is returned.
- If WNOHANG is not specified and there are valid processes to
report on, but there is no status available, the calling process is blocked
until status becomes available, at which time the return code is set to the
pid of the process for which status is available.
Error Return
If unsuccessful, the waitpid function returns a value of
-1 and sets errno to one of the following:
- ECHILD
- The process specified by the pid parameter does not
exist.
- EINVAL
- The value of the options argument is not valid.
Programming Considerations
- If there are any queued signals for the calling ECB to handle, these
signals are handled after the status of child processes is checked.
Signals that are received while waiting for child process status are handled
as they are received. This means that if the signal function
was used to install signal handlers, the placement of the waitpid
function in the code is subject to the same restrictions as the
raise function.
- If the waitpid function is coded to wait for a specific child
process to exit and while the parent is waiting for that process, a different
child process exits first; the exit status of the first child process is
maintained for the parent process to query with a subsequent wait
or waitpid call.
- If the signal function was coded to ignore SIGCHLD signals,
exit status of the exiting child processes is not available. The
waitpid function will return immediately without status if WNOHANG
is specified. If WNOHANG is not specified, the waitpid
function will not return until all child processes have exited, at which time
it returns with a value of -1 and errno is set to
ECHILD.
Examples
The following example shows how the waitpid function is used to
wait for a single child process to exit and query its exit status.
#include <sysapi.h>
#include <signal.h>
#include <sys/wait.h>
·
·
·
pid_t child_pid;
pid_t rc_pid;
int chld_state;
int my_opt=WNOHANG;
·
·
·
/* Create a child process*/
child_pid = tpf_fork(&create_parameters);
·
·
·
/* Check status of child process*/
rc_pid = waitpid( child_pid, &chld_state, WNOHANG);
if (rc_pid > 0)
{
if (WIFEXITED(chld_state)) {
printf("Child exited with RC=%d\n",WEXITSTATUS(chld_state));
}
if (WISIGNALED(chld_state)) {
printf("Child exited via signal %d\n",WTERMSIG(chld_state));
}
}
else
/* If no error, continue*/
{
if (rc_pid < 0) {
if (errno == ECHILD) {
printf("Child does not exist\n");
}
else {
printf("Bad argument passed to waitpid\n");
abort();
}
}
}
·
·
·
Related Information