Chapter Contents |
Previous |
Next |
waitpid |
Portability: | POSIX.1 conforming |
SYNOPSIS | |
DESCRIPTION | |
Analyzing Status Information | |
RETURN VALUE | |
CAUTIONS | |
PORTABILITY | |
EXAMPLE | |
RELATED FUNCTIONS |
SYNOPSIS |
#include <sys/types.h> #include <sys/wait.h> pid_t waitpid(pid_t pid, int *statusPtr, int options);
DESCRIPTION |
waitpid
suspends the calling process until a specified process terminates.
When the specified process ends, status information from the terminating process
is stored in the location pointed to by
statusPtr
and the calling process resumes execution. If the specified
process has already ended when the
waitpid
function is called and the system has status information, the
return from
waitpid
occurs
immediately. A return from the
waitpid
function also occurs if a signal is received and is not ignored.
pid
pid
is greater than 0, the calling process waits for the process whose
process identification number (PID) is equal to the value specified by
pid
.
pid
is equal to 0, the calling process waits for the process whose
process group ID is equal to the PID of the calling process.
pid
is equal to -1, the calling process waits for any child process
to terminate.
pid
is less than -1, the calling process waits for the process whose
process group ID is equal to the absolute value of
pid
.
statusPtr
waitpid
: if
waitpid
is called with
NULL
as the
statusPrt
value, no status information is returned. Assuming that this situation does
not apply, the macros described in Analyzing Status Information are used to analyze the status
information.
options
waitpid
function. Either of the
following option flags may be specified, or they can be combined with a bitwise
inclusive OR operator:
WNOHANG
waitpid
to return status information immediately,
without waiting for the specified process to terminate. Normally, a call to
waitpid
causes the calling process
to be blocked until status information from the specified process is available;
the
WNOHANG
option prevents
the calling process from being blocked. If status information is not available,
waitpid
returns a
0
.
WUNTRACED
waitpid
to return status information for a specified
process that has either stopped or terminated. Normally, status information
is returned only for terminated processes.
After
the call to
waitpid
, status information stored
at the location pointed to by
statusPtr
can be evaluated with the following macros:
WIFEXITED(*statusPtr)
WEXITSTATUS(*statusPtr)
exit
or
_exit
function or returned from
main
.
WIFSIGNALED(*statusPtr)
WTERMSIG(*statusPtr)
WIFSTOPPED(*statusPtr)
WSTOPSIG(*statusPtr)
RETURN VALUE |
If successful,
waitpid
returns the process ID of the terminated process whose status
was reported. If unsuccessful, a
-1
is returned.
CAUTIONS |
If
W_NOHANG
is not specified, the
waitpid
function will terminate if a signal managed by USS arrives
before any child process has terminated. It will not terminate if a signal
managed by SAS/C arrives; the signal will remain pending until the completion
of
waitpid
.
PORTABILITY |
The
waitpid
function is defined by the POSIX.1 standard.
Older UNIX programs may manipulate the status
information
stored at the location pointed to by
statusPtr
directly. These programs must be changed to use the POSIX.1
defined macros. This is necessary because USS and SAS/C use different values
for signal numbers, and the status codes reflect USS signal numbers, not SAS/C
signal numbers. For instance, a process terminated with the
SIGKILL
signal will have status code
9
, but the comparison (
status == SIGKILL
) will fail. A correct POSIX-conforming
test for process termination by
SIGKILL
would be as follows:
(WIFSIGNALED(status) && WTERMSIG(status) == SIGKILL)
The
WTERMSIG
macro performs conversion of USS signal numbers to SAS/C signal numbers.
EXAMPLE |
The following example illustrates the
use of
waitpid
to wait
for a process to end:
#include <sys/types.h> #include <sys/wait.h> #include <unistd.h> #include <time.h> #include <stdio.h> #include <stdlib.h> int main(void) { int i, status; pid_t childID, endID; time_t when; if ((childID = fork()) == -1) { /* Start a child process. */ perror("fork error"); exit(EXIT_FAILURE); } else if (childID == 0) { /* This is the child. */ time(&when); printf("Child process started at %s", ctime(&when)); sleep(10); /* Sleep for 10 seconds. */ exit(EXIT_SUCCESS); } else { /* This is the parent. */ time(&when); printf("Parent process started at %s", ctime(&when)); /* Wait 15 seconds for child process to terminate. */ for(i = 0; i < 15; i++) { endID = waitpid(childID, &status, WNOHANG|WUNTRACED); if (endID == -1) { /* error calling waitpid */ perror("waitpid error"); exit(EXIT_FAILURE); } else if (endID == 0) { /* child still running */ time(&when); printf("Parent waiting for child at %s", ctime(&when)); sleep(1); } else if (endID == childID) { /* child ended */ if (WIFEXITED(status)) printf("Child ended normally.n"); else if (WIFSIGNALED(status)) printf("Child ended because of an uncaught signal.n"); else if (WIFSTOPPED(status)) printf("Child process has stopped.n"); exit(EXIT_SUCCESS); } } } }
RELATED FUNCTIONS |
Chapter Contents |
Previous |
Next |
Top of Page |
Copyright © 2001 by SAS Institute Inc., Cary, NC, USA. All rights reserved.