waitid()
Wait for a child process to change state
Synopsis:
#include <sys/wait.h>
int waitid( idtype_t idtype,
id_t id,
siginfo_t * infop,
int options );
Arguments:
- idtype
- Which children you want to wait for:
- P_PID — the child with a process ID of
(pid_t)id. - P_PGID — any child with a process group ID equal
to
(pid_t)id. - P_ALL — any child; id is ignored.
- P_PID — the child with a process ID of
- id
- The process or process group ID that you want to wait for, depending on the value of idtype.
- infop
- A pointer to a siginfo_t structure, where the function can store the current state of the child.
- options
- You must specify at least 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.
- WSTOPPED — wait for and return the process status of any child that has stopped because it received a signal. In QNX OS, this is the same as WUNTRACED.
- WTRAPPED (a Unix extension) — wait for the process(es) to stop at a debugger point of interest.
- 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.
Library:
libc
Use the -l c option to qcc to link against this library. This library is usually included automatically.
Description:
The waitid() function suspends the calling thread until one of its children changes state. It records the current state of a child in the structure pointed to by infop. If a child process changed state prior to the call to waitid(), waitid() returns immediately.
- In order to wait for the status of a terminated child process whose real or saved user ID is different from the calling process's real or effective user ID, your process must have the PROCMGR_AID_WAIT ability enabled. For more information, see procmgr_ability().
- If the parent process sets the action for SIGCHLD to SIG_IGN, its children won't enter the zombie state, and it won't be able to use the wait*() functions to wait on their deaths.
If waitid() returns because a child process was found that satisfied the conditions indicated by the arguments idtype and options, then the structure pointed to by infop is filled in by the system with the status of the process. The si_signo member is always SIGCHLD.
If idtype is P_ALL and options is
WEXITED|WTRAPPED, waitid() is equivalent to
wait().
Returns:
- 0
- One of the children changed its state. If WNOHANG was used, 0 can be returned (indicating no error); however, no children may have changed state if info->si_pid is 0.
- -1
- An error occurred (errno is set).
Errors:
- ECHILD
- The set of processes specified by idtype and id doesn't contain any unwaited-for processes.
- EFAULT
- The infop argument points to an illegal address.
- EINTR
- The waitid() function was interrupted by a signal.
- EINVAL
- An invalid value was specified for options, or idtype and id specify an invalid set of processes.
- EPERM
- The calling process doesn't have the required permission; see procmgr_ability().
Classification:
| Safety: | |
|---|---|
| Cancellation point | Yes |
| Signal handler | Yes |
| Thread | Yes |