waitpid

Sleep until all processes whose PIDs have been specified have exited

$ waitpid [pid1 pid2 ...]

$ waitpid [[-t|--timeout]] [n] [pid1 pid2 ...]

$ waitpid [[-e|--exited]] [pid1 pid2 ...]

$ waitpid [[-c|--count]] [n] [pid1 pid2 ...]

$ waitpid [[-h|--help]]

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

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

waitpid is a system call, not a shell command. It is invoked within C/C++ programs to manage child processes.

pid_t pid
    Specifies the set of child processes to wait for.
> 0: Wait for the child with the process ID pid.
= 0: Wait for any child process in the same process group as the caller.
= -1: Wait for any child process.
< -1: Wait for any child process in the process group whose ID is equal to the absolute value of pid.

int *status
    A pointer to an integer where the exit status of the child will be stored. This value can be interpreted using macros like WIFEXITED, WEXITSTATUS, etc. If status is NULL, the child's status is not returned.

int options
    A bit mask that modifies the behavior of waitpid. Multiple options can be combined using a bitwise OR (|).
WNOHANG: Do not block; return immediately if no child has exited.
WUNTRACED: Return for children that are stopped (e.g., by SIGSTOP or SIGTSTP).
WCONTINUED: Return for children that have been continued by delivery of SIGCONT.

waitpid is a system call that suspends the execution of the calling process until a child specified by pid changes state. A state change can be termination, being stopped by a signal, or being continued after being stopped. It provides more control than the simpler wait(2) system call, allowing the caller to specify which child process to wait for and whether to block or return immediately if no child has changed state.

When a child process terminates, it becomes a "zombie" process. waitpid reaps these zombies, releasing their resources back to the system. The status argument, if not NULL, is used to store information about the child's state change, which can then be interpreted using a set of macros like WIFEXITED, WEXITSTATUS, etc. The options argument modifies the behavior of waitpid, for example, preventing it from blocking (WNOHANG) or allowing it to return for stopped or continued children.

waitpid is a system call, which means it's a function used within programming languages (primarily C/C++), not a command directly executed in a shell.

Misinterpreting the status value without using the provided macros (e.g., WIFEXITED) can lead to incorrect logic.

If a child process is not waited for (i.e., its parent does not call waitpid or wait), it becomes a 'zombie' process, consuming a small amount of system resources until its parent terminates or it is explicitly reaped by another process (e.g., init if the parent exits).

On success, waitpid returns the process ID of the child whose state has changed. If WNOHANG was specified and no child has changed state, it returns 0. On error, it returns -1, and errno is set to indicate the error.

Common errors include:
ECHILD: No child (or process specified by pid) exists or could be found, or the pid refers to a child that has already been waited for.
EINTR: The call was interrupted by a signal.
EINVAL: An invalid value was provided for options.

To interpret the integer value returned in status, a set of macros should be used:
WIFEXITED(status): True if the child exited normally.
WEXITSTATUS(status): Returns the exit status of the child (only if WIFEXITED is true).
WIFSIGNALED(status): True if the child terminated because of a signal.
WTERMSIG(status): Returns the signal number that caused the child to terminate (only if WIFSIGNALED is true).
WIFSTOPPED(status): True if the child was stopped by delivery of a signal.
WSTOPSIG(status): Returns the signal number that caused the child to stop (only if WIFSTOPPED is true).
WIFCONTINUED(status): True if the child was continued by delivery of SIGCONT (only if WCONTINUED option was set).

The waitpid system call was introduced to provide more granular control over process waiting compared to the original wait(2) system call. While wait(2) waits for any child process, waitpid allows specifying a particular child or a group of children, as well as non-blocking options. This enhanced functionality became crucial for more complex process management scenarios, especially in multi-process server applications and shell implementations. It is a fundamental part of the POSIX standard, ensuring its widespread availability and consistent behavior across various Unix-like operating systems.

wait(2), waitid(2), wait4(2), fork(2), exit(3), _exit(2), kill(2), ptrace(2)