1wait(3UCB)         SunOS/BSD Compatibility Library Functions        wait(3UCB)
2
3
4

NAME

6       wait,  wait3, wait4, waitpid, WIFSTOPPED, WIFSIGNALED, WIFEXITED - wait
7       for process to terminate or stop
8

SYNOPSIS

10       /usr/ucb/cc [ flag ... ] file ...
11       #include <sys/wait.h>
12
13       int wait(statusp)
14       int *statusp;
15
16
17       int waitpid(pid, statusp, options)
18       int pid;
19       int *statusp;
20       int options;
21
22
23       #include <sys/time.h>
24       #include <sys/resource.h>
25
26       int wait3(statusp, options, rusage)
27       int *statusp;
28       int options;
29       struct rusage *rusage;
30
31
32       int wait4(pid, statusp, options, rusage)
33       int pid;
34       int *statusp;
35       int options;
36       struct rusage *rusage;
37
38
39       WIFSTOPPED(status)
40       int status;
41
42
43       WIFSIGNALED(status)
44       int status;
45
46
47       WIFEXITED(status)
48       int status;
49
50

DESCRIPTION

52       The wait() function delays its caller until a signal is received or one
53       of its child processes terminates or stops due to tracing. If any child
54       process has died or stopped due  to  tracing  and  this  has  not  been
55       reported  using  wait(),  return is immediate, returning the process ID
56       and exit status of one of those children. If  that  child  process  has
57       died,  it  is  discarded. If there are no children, return is immediate
58       with the value −1 returned. If there are only running  or  stopped  but
59       reported children, the calling process is blocked.
60
61
62       If  status  is  not  a  NULL  pointer, then on return from a successful
63       wait() call the status of the child process whose  process  ID  is  the
64       return value of wait() is stored in the wait() union pointed to by sta‐
65       tus. The w_status member of that union is  an  int;  it  indicates  the
66       cause of termination and other information about the terminated process
67       in the following manner:
68
69           o      If the low-order 8 bits of w_status are equal to  0177,  the
70                  child  process  has  stopped;  the 8 bits higher up from the
71                  low-order 8 bits of w_status contain the number of the  sig‐
72                  nal  that  caused  the  process  to  stop. Seeptrace(3C) and
73                  sigvec(3UCB).
74
75           o      If the low-order 8 bits of w_status are non-zero and are not
76                  equal to 0177, the child process terminated due to a signal;
77                  the low-order 7 bits of w_status contain the number  of  the
78                  signal that terminated the process. In addition, if the low-
79                  order seventh bit of w_status (that is, bit 0200) is set,  a
80                  ``core   image''   of   the   process   was   produced;  see
81                  sigvec(3UCB).
82
83           o      Otherwise, the child process terminated  due  to  an  exit()
84                  call;  the  8  bits  higher  up from the low-order 8 bits of
85                  w_status contain the low-order 8 bits of the  argument  that
86                  the child process passed to exit(); see exit(2).
87
88
89       waitpid()  behaves identically to wait() if   pid has a value of −1 and
90       options has a value of zero. Otherwise, the behavior  of  waitpid()  is
91       modified by the values of   pid and options as follows:
92
93
94       pid  specifies  a set of child processes for which status is requested.
95       waitpid() only returns the status of a child process from this set.
96
97           o      If  pid is equal to −1, status is requested  for  any  child
98                  process.  In  this  respect, waitpid() is then equivalent to
99                  wait().
100
101           o      If  pid is greater than zero, it specifies the process ID of
102                  a single child process for which status is requested.
103
104           o      If   pid is equal to zero, status is requested for any child
105                  process whose process group ID is equal to that of the call‐
106                  ing process.
107
108           o      If   pid  is less than −1, status is requested for any child
109                  process whose process group ID  is  equal  to  the  absolute
110                  value of pid.
111
112
113       options is constructed from the bitwise inclusive OR of zero or more of
114       the following flags, defined in the header <sys/wait.h>:
115
116       WNOHANG      waitpid()  does  not  suspend  execution  of  the  calling
117                    process  if status is not immediately available for one of
118                    the child processes specified by pid.
119
120
121       WUNTRACED    The status of any child processes specified  by  pid  that
122                    are  stopped,  and  whose status has not yet been reported
123                    since they stopped, are also reported  to  the  requesting
124                    process.
125
126
127
128       wait3()  is an alternate interface that allows both non-blocking status
129       collection and the collection of the status of children stopped by  any
130       means.  The status parameter is defined as above. The options parameter
131       is used to indicate the call should not block if there are no processes
132       that  have status to report (WNOHANG), and/or that children of the cur‐
133       rent process that are stopped due to a SIGTTIN,  SIGTTOU,  SIGTSTP,  or
134       SIGSTOP signal are eligible to have their status reported as well (WUN‐
135       TRACED). A terminated child is discarded after it reports status, and a
136       stopped process will not report its status more than once. If rusage is
137       not a NULL pointer, a summary of the resources used by  the  terminated
138       process  and  all its children is returned. Only the user time used and
139       the system time used are currently  available.  They  are  returned  in
140       rusage.ru_utime and rusage.ru_stime, respectively.
141
142
143       When  the  WNOHANG  option is specified and no processes have status to
144       report, wait3() returns 0. The WNOHANG and  WUNTRACED  options  may  be
145       combined by ORing the two values.
146
147
148       wait4()  is  another alternate interface.  With a pid argument of 0, it
149       is equivalent to wait3(). If pid has  a  nonzero  value,  then  wait4()
150       returns status only for the indicated process ID, but not for any other
151       child processes.
152
153
154       WIFSTOPPED, WIFSIGNALED, WIFEXITED, are macros that  take  an  argument
155       status,  of  type  int, as returned by wait(), or wait3(), or  wait4().
156       WIFSTOPPED evaluates to true (1) when the process for which the  wait()
157       call was made is stopped, or to false (0) otherwise. WIFSIGNALED evalu‐
158       ates to true when the process was terminated with a  signal.  WIFEXITED
159       evaluates to true when the process exited by using an exit(2) call.
160

RETURN VALUES

162       If  wait()or  waitpid()  returns  due  to a stopped or terminated child
163       process, the process ID  of  the  child  is  returned  to  the  calling
164       process. Otherwise, a value of −1 is returned and errno is set to indi‐
165       cate the error.
166
167
168       If wait() or waitpid() return due to the delivery of a  signal  to  the
169       calling  process,  a value of −1 is returned and errno is set to EINTR.
170       If waitpid() function was invoked with WNOHANG set in options,  it  has
171       at  least  one  child  process specified by pid for which status is not
172       available, and status is not available for  any  process  specified  by
173       pid, a value of zero is returned. Otherwise, a value of −1 is returned,
174       and errno is set to indicate the error.
175
176
177       wait3() and  wait4() return 0 if WNOHANG is specified and there are  no
178       stopped  or  exited  children,  and returns the process ID of the child
179       process if it returns due to a stopped  or  terminated  child  process.
180       Otherwise,  they  returns  a value of −1 and sets errno to indicate the
181       error.
182

ERRORS

184       The wait(), wait3() and wait4() functions will fail and return  immedi‐
185       ately if:
186
187       ECHILD    The  calling  process has no existing unwaited-for child pro‐
188                 cesses.
189
190
191       EFAULT    The status or rusage arguments point to an illegal address.
192
193
194
195       waitpid() may set errno to:
196
197       ECHILD    The process or process group specified by pid does not  exist
198                 or is not a child of the calling process.
199
200
201       EINTR     The  function  was  interrupted by a signal. The value of the
202                 location pointed to by statusp is undefined.
203
204
205       EINVAL    The value of options is not valid.
206
207
208
209       The wait(), wait3(), and wait4() functions will terminate  prematurely,
210       return  −1,  and  set errno to EINTR upon the arrival of a signal whose
211       SV_INTERRUPT bit in its flags field is set (see sigvec(3UCB) and sigin‐
212       terrupt(3UCB)). signal(3UCB), sets this bit for any signal it catches.
213

SEE ALSO

215       exit(2),  getrusage(3C),  ptrace(3C),  siginterrupt(3UCB),  signal(3C),
216       signal(3UCB), sigvec(3UCB), wait(3C), waitpid(3C)
217

NOTES

219       Use of these interfaces should be restricted to only applications writ‐
220       ten  on  BSD platforms.  Use of these interfaces with any of the system
221       libraries or in multi-thread applications is unsupported.
222
223
224       If a parent process terminates without waiting  on  its  children,  the
225       initialization process (process ID = 1) inherits the children.
226
227
228       The  wait(), wait3(), and wait4() functions are automatically restarted
229       when a process receives a signal while awaiting termination of a  child
230       process,  unless the SV_INTERRUPT bit is set in the flags for that sig‐
231       nal.
232
233
234       Calls to wait() with an argument of  0 should be cast to type `int  *',
235       as in:
236
237         wait((int *)0)
238
239
240
241
242       Previous  SunOS  releases used union wait*statusp and union wait status
243       in place of int *statusp and int status. The union contained  a  member
244       w_status that could be treated in the same way as status.
245
246
247       Other  members of the wait union could be used to extract this informa‐
248       tion more conveniently:
249
250           o      If the w_stopval member had the value WSTOPPED,   the  child
251                  process  had  stopped; the value of the w_stopsig member was
252                  the signal that stopped the process.
253
254           o      If the w_termsig member was non-zero, the child process ter‐
255                  minated  due  to a signal; the value of the w_termsig member
256                  was the number of the signal that  terminated  the  process.
257                  If  the w_coredump member was non-zero, a core dump was pro‐
258                  duced.
259
260           o      Otherwise, the child process terminated due  to  a  call  to
261                  exit().  The value of the w_retcode member was the low-order
262                  8 bits of the argument that  the  child  process  passed  to
263                  exit().
264
265
266       union  wait  is obsolete in light of the new specifications provided by
267       IEEE Std 1003.1-1988 and endorsed by SVID89 and XPG3. SunOS Release 4.1
268       supports unionwait for backward compatibility, but it will disappear in
269       a future release.
270
271
272
273SunOS 5.11                        30 Oct 2007                       wait(3UCB)
Impressum