1waitpid(3C)              Standard C Library Functions              waitpid(3C)
2
3
4

NAME

6       waitpid - wait for child process to change state
7

SYNOPSIS

9       #include <sys/types.h>
10       #include <sys/wait.h>
11
12       pid_t waitpid(pid_t pid, int *stat_loc, int options);
13
14

DESCRIPTION

16       The  waitpid()  function  will  suspend execution of the calling thread
17       until status information for one of its terminated child  processes  is
18       available, or until delivery of a signal whose action is either to exe‐
19       cute a signal-catching function or to terminate the  process.  If  more
20       than  one  thread  is  suspended  in  waitpid(), wait(3C), or waitid(2)
21       awaiting termination of the  same  process,  exactly  one  thread  will
22       return  the  process  status at the time of the target process termina‐
23       tion. If status information is available prior to  the  call  to  wait‐
24       pid(), return will be immediate.
25
26
27       The pid argument specifies a set of child processes for which status is
28       requested, as follows:
29
30           o      If pid is less than (pid_t)−1, status is requested  for  any
31                  child  process whose process group  ID is equal to the abso‐
32                  lute value of pid.
33
34           o      If pid is equal to (pid_t)−1, status is  requested  for  any
35                  child process.
36
37           o      If   pid  is  equal  to (pid_t)0 status is requested for any
38                  child process whose process group  ID is equal  to  that  of
39                  the calling process.
40
41           o      If   pid  is greater than (pid_t)0, it specifies the process
42                  ID of the child process for which status is requested.
43
44
45       One instance of a SIGCHLD signal is queued for each child process whose
46       status  has changed. If waitpid() returns because the status of a child
47       process is available, and WNOWAIT was not  specified  in  options,  any
48       pending  SIGCHLD  signal  associated  with the process ID of that child
49       process is discarded. Any other pending SIGCHLD signals remain pending.
50
51
52       If the calling process has SA_NOCLDWAIT  set  or  has  SIGCHLD  set  to
53       SIG_IGN  and the process has no unwaited children that were transformed
54       into zombie processes, it will block until all of its  children  termi‐
55       nate, and waitpid() will fail and set errno to ECHILD.
56
57
58       If  waitpid()  returns  because the status of a child process is avail‐
59       able, then that  status may be evaluated with  the  macros  defined  by
60       wait.h(3HEAD)  If the calling process had specified a non-zero value of
61       stat_loc, the status of the child process will be stored in  the  loca‐
62       tion pointed to by stat_loc.
63
64
65       The  options  argument  is constructed from the bitwise-inclusive OR of
66       zero  or  more  of  the  following  flags,  defined   in   the   header
67       <sys/wait.h>:
68
69       WCONTINUED    The  status  of  any continued child process specified by
70                     pid, whose status has not been reported since it  contin‐
71                     ued, is also reported to the calling process.
72
73
74       WNOHANG       The  waitpid() function will not suspend execution of the
75                     calling process if status is  not  immediately  available
76                     for one of the child processes specified by pid.
77
78
79       WNOWAIT       Keep  the process whose status is returned in stat_loc in
80                     a waitable state. The process may  be  waited  for  again
81                     with identical results.
82
83
84       WUNTRACED     The  status  of any child processes specified by pid that
85                     are stopped, and whose status has not yet  been  reported
86                     since  they  stopped,  is  also  reported  to the calling
87                     process. WSTOPPED is a synonym for WUNTRACED.
88
89

RETURN VALUES

91       If waitpid() returns because the status of a child  process  is  avail‐
92       able,   it returns a value equal to the process ID of the child process
93       for which status is reported.  If waitpid() returns due to the delivery
94       of  a signal to the calling process, −1 is returned and errno is set to
95       EINTR.  If waitpid() was invoked with WNOHANG set in options, it has at
96       least one child process specified by pid for which status is not avail‐
97       able, and status is not available for any  process  specified  by  pid,
98       then  0  is  returned.   Otherwise,  −1 is returned and errno is set to
99       indicate the error.
100

ERRORS

102       The waitpid() function will fail if:
103
104       ECHILD    The process or process group specified by pid does not  exist
105                 or  is  not a child of the calling process or can never be in
106                 the states specified by options.
107
108
109       EINTR     The waitpid() function was interrupted due to the receipt  of
110                 a signal sent by the calling process.
111
112
113       EINVAL    An invalid value was specified for options.
114
115

USAGE

117       With options equal to 0 and  pid equal to (pid_t)−1, waitpid() is iden‐
118       tical to wait(3C). The waitpid() function is implemented as a  call  to
119       the more general waitid(2) function.
120

ATTRIBUTES

122       See attributes(5) for descriptions of the following attributes:
123
124
125
126
127       ┌─────────────────────────────┬─────────────────────────────┐
128       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
129       ├─────────────────────────────┼─────────────────────────────┤
130       │Interface Stability          │Committed                    │
131       ├─────────────────────────────┼─────────────────────────────┤
132       │MT-Level                     │Async-Signal-Safe            │
133       ├─────────────────────────────┼─────────────────────────────┤
134       │Standard                     │See standards(5).            │
135       └─────────────────────────────┴─────────────────────────────┘
136

SEE ALSO

138       Intro(2),    exec(2),   exit(2),   fork(2),   pause(2),   sigaction(2),
139       ptrace(3C),  signal(3C),  siginfo.h(3HEAD),  wait(3C),   wait.h(3HEAD),
140       attributes(5), standards(5)
141
142
143
144SunOS 5.11                        7 Dec 2007                       waitpid(3C)
Impressum