waitpid()

Wait for a child process to stop or terminate

Synopsis:

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

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

Arguments:

pid

The set of child processes that you want to get status information for:

• less than -1 — any child process whose process group ID is equal to the absolute value of pid.
• -1 — any child process
• 0 — any child process whose process group ID is equal to that of the calling process.
• greater than 0 — the single child process with this ID.

stat_loc

NULL, or a pointer a location where the function can store the terminating status of the child process. For information about macros that extract information from this status, see “Status macros” in the documentation for wait().

options

A combination of zero or more of the following flags:

• WCONTINUED — return the status for any child that was stopped and has been continued.
• WEXITED — wait for the process(es) to exit.
• WNOHANG — return immediately if there are no children to wait for.
• WNOWAIT — keep the process in a waitable state. This doesn't affect the state of the process; the process may be waited for again after this call completion.
• WSTOPPED — wait for and return the process status of any child that has stopped because it received a signal.
• WUNTRACED — report the status of a stopped child process.

Library:

libc

Use the -l c option to qcc to link against this library. This library is usually included automatically.

Description:

The waitpid() function suspends execution of the calling thread until status information from one of its terminated child processes is available, or until the delivery of a signal whose action is either to terminate the process or execute a signal handler. If status information is available prior to the call to waitpid(), the return is immediate.

The waitpid() function behaves the same as wait() when passed a pid argument of -1, and the options argument has a value of zero.

Only one of the WIFEXITED(stat_val) and WIFSIGNALED(stat_val) macros can evaluate to a nonzero value.

Returns:

The process ID of the terminating child process on success. If waitpid() is invoked with WNOHANG set in options, it has at least one child process specified by pid for which status isn't available, and status isn't available for any process specified by pid, a value of zero is returned. On delivery of a signal, waitpid() returns -1, and errno is set to EINTR.

Errors:

ECHILD

The calling process has no existing unwaited-for child processes that meet the criteria set by pid.

EINTR

The function was interrupted by a signal. The value of the location pointed to by stat_loc is undefined.

EINVAL

The value of the options argument isn't valid.

Classification:

POSIX 1003.1

See also:

spawn(), wait(), wait3(), wait4(), waitid()

Processes and Threads chapter of Getting Started with QNX Neutrino