wait -- Wait for Child Process to End

SYNOPSIS

 #include <sys/types.h>
 #include <sys/wait.h>

 pid_t wait(int *statusPtr);

DESCRIPTION

wait suspends the calling process until one of its child processes ends. Usually, the wait function is called before a child process terminates, in which case the parent process waits for a child process to end; however, if the system already has information about a terminated child process when wait is called, the return from wait occurs immediately. wait also returns if a signal is received and is not ignored.

Status information for the terminating child process is usually stored at the location pointed to by statusPtr; however, there is one situation when status information is not available after a call to wait: if wait is called with NULL as the statusPrt value, no status information is returned. Assuming that this situation does not apply, the macros described in the next section are used to analyze the status information.

Analyzing Status Information

After the call to wait, status information stored at the location pointed to by statusPtr can be evaluated with the following macros:

WIFEXITED(*statusPtr): evaluates to a nonzero (true) value if the child process terminates normally.
WEXITSTATUS(*statusPtr): if the child process terminates normally, this macro evaluates to the lower 8 bits of the value passed to the exit or _exit function or returned from main.
WIFSIGNALED(*statusPtr): evaluates to a nonzero (true) value if the child process terminates because of an unhandled signal.
WTERMSIG(*statusPtr): if the child process ends by a signal that was not caught, this macro evaluates to the number of that signal.

RETURN VALUE

If successful, wait returns the process ID of the child process. If unsuccessful, a -1 is returned.

CAUTIONS

The wait function will terminate if a signal managed by OpenEdition 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 wait.

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 OpenEdition and SAS/C use different values for signal numbers, and the status codes reflect OpenEdition 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 OpenEdition signal numbers to SAS/C signal numbers.

EXAMPLE

The following example illustrates the use of wait to suspend a parent process until a child terminates:

  #include <sys/types.h>
  #include <sys/wait.h>
  #include <unistd.h>
  #include <stdio.h>
  #include <stdlib.h>

  main()
  {
     int status, randomNumber, seed;
     char buffer[80];
     pid_t pid;

     if ((pid = fork()) == -1) {
          perror("fork error");
          exit(EXIT_FAILURE);
     }

     else if (pid == 0) {             /* start of child process      */
        printf("Child process started.n");
        printf("Enter a random seed.n");
        if(gets(buffer)) {
           seed = atoi(buffer);
           srand(seed);
        }
        randomNumber = rand();        /* random end to child process */
        if ((randomNumber % 2) == 0) {
           printf("Child process aborted; pid = %d.n", (int) pid);
           abort();
           fclose(stdout);
        }
        else {
           printf("Child process ended normally; pid = %d.n", (int) pid);
           exit(EXIT_SUCCESS);
        }
     }
     else {                           /* start of parent process     */
        printf("Parent process started.n");
        if ((pid = wait(&status)) == -1)
                                     /* Wait for child process.      */                                   */
           perror("wait error");
        else {                       /* Check status.                */
           if (WIFSIGNALED(status) != 0)
              printf("Child process ended because of signal %d.n",
                      WTERMSIG(status));
           else if (WIFEXITED(status) != 0)
              printf("Child process ended normally; status = %d.n",
                      WEXITSTATUS(status));
           else
              printf("Child process did not end normally.n");
        }
        printf("Parent process ended.n");
        exit(EXIT_SUCCESS);
     }
  }

RELATED FUNCTIONS

fork, waitpid