The GNU C Library - Process Completion

Process Completion

The functions described in this section are used to wait for a child process to terminate or stop, and determine its status. These functions are declared in the header file `sys/wait.h'.

Function pid_t waitpid (pid_t pid, int *status-ptr, int options)

The waitpid function is used to request status information from a child process whose process ID is pid. Normally, the calling process is suspended until the child process makes status information available by terminating.

Other values for the pid argument have special interpretations. A value of -1 or WAIT_ANY requests status information for any child process; a value of 0 or WAIT_MYPGRP requests information for any child process in the same process group as the calling process; and any other negative value - pgid requests information for any child process whose process group ID is pgid.

If status information for a child process is available immediately, this function returns immediately without waiting. If more than one eligible child process has status information available, one of them is chosen randomly, and its status is returned immediately. To get the status from the other eligible child processes, you need to call waitpid again.

The options argument is a bit mask. Its value should be the bitwise OR (that is, the `|' operator) of zero or more of the WNOHANG and WUNTRACED flags. You can use the WNOHANG flag to indicate that the parent process shouldn't wait; and the WUNTRACED flag to request status information from stopped processes as well as processes that have terminated.

The status information from the child process is stored in the object that status-ptr points to, unless status-ptr is a null pointer.

The return value is normally the process ID of the child process whose status is reported. If the WNOHANG option was specified and no child process is waiting to be noticed, the value is zero. A value of -1 is returned in case of error. The following errno error conditions are defined for this function:

EINTR

The function was interrupted by delivery of a signal to the calling process. See Interrupted Primitives.

ECHILD

There are no child processes to wait for, or the specified pid is not a child of the calling process.

EINVAL

An invalid value was provided for the options argument.

These symbolic constants are defined as values for the pid argument to the waitpid function.

WAIT_ANY

This constant macro (whose value is -1 ) specifies that waitpid should return status information about any child process.

WAIT_MYPGRP

This constant (with value 0 ) specifies that waitpid should return status information about any child process in the same process group as the calling process.

These symbolic constants are defined as flags for the options argument to the waitpid function. You can bitwise-OR the flags together to obtain a value to use as the argument.

WNOHANG

This flag specifies that waitpid should return immediately instead of waiting, if there is no child process ready to be noticed.

WUNTRACED

This flag specifies that waitpid should report the status of any child processes that have been stopped as well as those that have terminated.

Function pid_t wait (int *status-ptr)

This is a simplified version of waitpid , and is used to wait until any one child process terminates. The call:

	wait (&status)

is exactly equivalent to:

	waitpid (-1, &status, 0)

Function pid_t wait4 (pid_t pid, int *status-ptr, int options, struct rusage *usage)

If usage is a null pointer, wait4 is equivalent to waitpid (pid, status-ptr, options) .

If usage is not null, wait4 stores usage figures for the child process in *rusage (but only if the child has terminated, not if it has stopped). See Resource Usage.

This function is a BSD extension.

Here's an example of how to use waitpid to get the status from all child processes that have terminated, without ever waiting. This function is designed to be a handler for SIGCHLD , the signal that indicates that at least one child process has terminated.

	void
	sigchld_handler (int signum)
	{
	  int pid;
	  int status;
	  while (1)
	    {
	      pid = waitpid (WAIT_ANY, &status, WNOHANG);
	      if (pid < 0)
	        {
	          perror ("waitpid");
	          break;
	        }
	      if (pid == 0)
	        break;
	      notice_termination (pid, status);
	    }
	}