waitpid() — Wait for a Specific Child Process to End

Standards / Extensions C or C++ Dependencies
POSIX.1
XPG4
XPG4.2
 both  

Format

#define _OPEN_SYS
#include <sys/wait.h>

pid_t waitpid(pid_t pid, int *status_ptr, int options);

General Description

Suspends the calling process until a child process ends or is stopped. More precisely, waitpid() suspends the calling process until the system gets status information on the child. If the system already has status information on an appropriate child when waitpid() is called, waitpid() returns immediately. The waitpid() function also ends if the calling process receives a signal whose action is either to execute a signal handler or to end the process.

The waitpid() function is supported only in a POSIX program. For more information, see IBM XL C/C++ for z/VM Applications with OpenExtensions Services.
pid_t pid
Specifies the child processes the caller wants to wait for:
  • If pid is greater than 0, waitpid() waits for termination of the specific child whose process ID is equal to pid.
  • If pid is equal to 0, waitpid() waits for termination of any child whose process group ID is equal to that of the caller.
  • If pid is -1, waitpid() waits for any child process to end.
  • If pid is less than -1, waitpid() waits for the termination of any child whose process group ID is equal to the absolute value of pid.
int *status_ptr
Points to a location where waitpid() can store a status value. This status value is 0 if the child process explicitly returns a 0 status. Otherwise, it is a value that can be analyzed with the status analysis macros described in “Status Analysis Macros,” below.

The status_ptr pointer may also be NULL, in which case waitpid() ignores the child's return status.

int options
Specifies additional information for waitpid(). The options value is constructed from the bitwise inclusive OR of zero or more of the following manifests defined in the sys/wait.h header file:
WCONTINUED
Special Behavior for XPG4.2: Reports the status of any continued child processes as well as terminated ones. The WIFCONTINUED macro lets a process distinguish between a continued process and a terminated one.
WNOHANG
Demands status information immediately. If status information is immediately available on an appropriate child process, waitpid() returns this information. Otherwise, waitpid() returns immediately with an error code, indicating that the information was not available. In other words, WNOHANG checks child processes without causing the caller to be suspended.
WUNTRACED
Reports on stopped child processes as well as terminated ones. The WIFSTOPPED macro lets a process distinguish between a stopped process and a terminated one.

Special Behavior for XPG4.2

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 the children terminate; and waitpid() will fail and set errno to ECHILD.

Status Analysis Macros

If the status_ptr argument is not NULL, waitpid() places the child's return status in *status_ptr. You can analyze this return status with the following macros, defined in the sys/wait.h header file:
WIFEXITED(*status_ptr)
This macro evaluates to a nonzero (true) value if the child process ended normally (that is, if it returned from main(), or else called the exit() or uexit() function).
WEXITSTATUS(*status_ptr)
When WIFEXITED() is nonzero, WEXITSTATUS() evaluates to the low-order 8 bits of the status argument that the child passed to the exit() or uexit() function, or the value the child process returned from main().
WIFSIGNALED(*status_ptr)
This macro evaluates to a nonzero (true) value if the child process ended because of a signal that was not caught.
WTERMSIG(*status_ptr)
When WIFSIGNALED() is nonzero, WTERMSIG() evaluates to the number of the signal that ended the child process.
WIFSTOPPED(*status_ptr)
This macro evaluates to a nonzero (true) value if the child process is currently stopped. You should only use this macro after a waitpid() with the WUNTRACED option.
WSTOPSIG(*status_ptr)
When WIFSTOPPED() is nonzero, WSTOPSIG() evaluates to the number of the signal that stopped the child.
WIFCONTINUED(*status_ptr)
Special Behavior for XPG4.2: This macro evaluates to a nonzero (true) value if the child process has continued from a job control stop. You should only use this macro after a waitpid() with the WCONTINUED option.

Returned Value

If successful, waitpid() returns a value of the process (usually a child) whose status information has been obtained.

If WNOHANG was given, and the status information is not available for at least one process (usually a child), waitpid() returns a value of 0.

If unsuccessful, waitpid() returns a value of -1 and sets errno to one of the following values under the conditions described:
ECHILD
The process specified by pid does not exist or is not a child of the calling process, or the process group specified by pid does not exist or does not have any member process that is a child of the calling process.
EINTR
The waitpid() function was interrupted by a signal. The value of *status_ptr is undefined.
EINVAL
The value of options is incorrect.

Example

CBC3BW02

/* CBC3BW02
   The following function suspends the calling process using waitpid()
   until a child process ends.
 */
#define _OPEN_SYS
#include <sys/types.h>
#include <sys/wait.h>
#include <spawn.h>
#include <unistd.h>
#include <stdio.h>
#include <time.h>

main() {
  pid_t pid;
  time_t t;
  int status;

  if ((pid = spawn("childprog', 0, 0, 0, 0, 0)) < 0)
    perror("spawn() error");
  else do {
    if ((pid = waitpid(pid, &status, WNOHANG)) == -1)
      perror("wait() error");
    else if (pid == 0) {
      time(&t);
      printf("child is still running at %s", ctime(&t));
      sleep(1);
    }
    else {
      if (WIFEXITED(status))
        printf("child exited with status of %d\n", WEXITSTATUS(status));
      else puts("child did not exit successfully");
    }
  } while (pid == 0);
}

Output

child is still running at Fri Jun 16 11:05:43 1995
child is still running at Fri Jun 16 11:05:44 1995
child is still running at Fri Jun 16 11:05:45 1995
child is still running at Fri Jun 16 11:05:46 1995
child is still running at Fri Jun 16 11:05:47 1995
child is still running at Fri Jun 16 11:05:48 1995
child is still running at Fri Jun 16 11:05:49 1995
child exited with status of 1