Annotation of src/lib/libc/sys/wait.2, Revision 1.39.16.1
1.39.16.1! martin 1: .\" $NetBSD: wait.2,v 1.39 2016/11/20 09:38:37 wiz Exp $
1.6 cgd 2: .\"
3: .\" Copyright (c) 1980, 1991, 1993, 1994
4: .\" The Regents of the University of California. All rights reserved.
1.1 cgd 5: .\"
6: .\" Redistribution and use in source and binary forms, with or without
7: .\" modification, are permitted provided that the following conditions
8: .\" are met:
9: .\" 1. Redistributions of source code must retain the above copyright
10: .\" notice, this list of conditions and the following disclaimer.
11: .\" 2. Redistributions in binary form must reproduce the above copyright
12: .\" notice, this list of conditions and the following disclaimer in the
13: .\" documentation and/or other materials provided with the distribution.
1.24 agc 14: .\" 3. Neither the name of the University nor the names of its contributors
1.1 cgd 15: .\" may be used to endorse or promote products derived from this software
16: .\" without specific prior written permission.
17: .\"
18: .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
19: .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20: .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21: .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
22: .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
23: .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
24: .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25: .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
26: .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
27: .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28: .\" SUCH DAMAGE.
29: .\"
1.6 cgd 30: .\" @(#)wait.2 8.2 (Berkeley) 4/19/94
1.1 cgd 31: .\"
1.39.16.1! martin 32: .Dd September 2, 2019
1.1 cgd 33: .Dt WAIT 2
1.11 garbled 34: .Os
1.1 cgd 35: .Sh NAME
36: .Nm wait ,
1.28 christos 37: .Nm waitid ,
1.1 cgd 38: .Nm waitpid ,
1.28 christos 39: .Nm wait6 ,
1.1 cgd 40: .Nm wait4 ,
41: .Nm wait3
1.6 cgd 42: .Nd wait for process termination
1.12 kleink 43: .Sh LIBRARY
44: .Lb libc
1.1 cgd 45: .Sh SYNOPSIS
1.23 wiz 46: .In sys/wait.h
1.1 cgd 47: .Ft pid_t
48: .Fn wait "int *status"
1.3 jtc 49: .Ft pid_t
50: .Fn waitpid "pid_t wpid" "int *status" "int options"
1.28 christos 51: .Ft int
52: .Fn waitid "idtype_t idtype" "id_t id" "siginfo_t *info" "int options"
1.23 wiz 53: .In sys/resource.h
1.1 cgd 54: .Ft pid_t
55: .Fn wait3 "int *status" "int options" "struct rusage *rusage"
56: .Ft pid_t
57: .Fn wait4 "pid_t wpid" "int *status" "int options" "struct rusage *rusage"
1.28 christos 58: .Ft pid_t
1.33 christos 59: .Fn wait6 "idtype_t idtype" "id_t id" "int *status" "int options" "struct wrusage *wrusage" "siginfo_t *infop"
1.1 cgd 60: .Sh DESCRIPTION
61: The
62: .Fn wait
63: function suspends execution of its calling process until
64: .Fa status
65: information is available for a terminated child process,
66: or a signal is received.
1.15 wiz 67: On return from a successful
1.1 cgd 68: .Fn wait
1.15 wiz 69: call,
1.1 cgd 70: the
71: .Fa status
72: area contains termination information about the process that exited
73: as defined below.
74: .Pp
75: The
76: .Fn wait4
1.28 christos 77: and
78: .Fn wait6
1.1 cgd 79: call provides a more general interface for programs
80: that need to wait for certain child processes,
1.5 jtc 81: that need resource utilization statistics accumulated by child processes,
1.1 cgd 82: or that require options.
83: The other wait functions are implemented using
84: .Fn wait4 .
1.28 christos 85: or
86: .Fn wait6 .
1.1 cgd 87: .Pp
88: The
1.28 christos 89: .Fn wait6
90: function is the most general function in this family and its distinct
91: features are:
92: .Pp
93: All of the desired process statuses to be waited on must be explicitly
94: specified in
95: .Fa options .
96: The
97: .Fn wait ,
98: .Fn waitpid ,
99: .Fn wait3 ,
100: and
101: .Fn wait4
102: functions all implicitly wait for exited and trapped processes,
103: but the
104: .Fn waitid
105: and
106: .Fn wait6
107: functions require the corresponding
108: .Dv WEXITED
109: and
110: .Dv WTRAPPED
111: flags to be explicitly specified.
112: This allows waiting for processes which have experienced other
113: status changes without having to also handle the exit status from
114: terminated processes.
115: .Pp
116: The
117: .Fn wait6
118: function accepts a
119: .Fa wrusage
120: argument which points to a structure defined as:
121: .Bd -literal
122: struct wrusage {
123: struct rusage wru_self;
124: struct rusage wru_children;
125: };
126: .Ed
127: .Pp
128: This allows the calling process to collect resource usage statistics
129: from both its own child process as well as from its grand children.
130: When no resource usage statistics are needed this pointer can be
131: .Dv NULL .
132: .Pp
133: The last argument
134: .Fa infop
135: must be either
136: .Dv NULL
137: or a pointer to a
138: .Fa siginfo_t
139: structure.
140: If
141: .Pf non- Dv NULL ,
142: the structure is filled with the same data as for a
143: .Dv SIGCHLD
144: signal delivered when the process changed state.
145: .Pp
146: The set of child processes to be queried is specified by the arguments
147: .Fa idtype
148: and
149: .Fa id .
150: The separate
151: .Fa idtype
152: and
153: .Fa id
154: arguments support many other types of
1.29 wiz 155: identifiers in addition to process IDs and process group IDs.
1.28 christos 156: .Bl -bullet -offset indent
157: .It
158: If
159: .Fa idtype
160: is
161: .Dv P_PID ,
162: .Fn waitid
163: and
164: .Fn wait6
165: wait for the child process with a process ID equal to
166: .Dv (pid_t)id .
167: .It
168: If
169: .Fa idtype
170: is
171: .Dv P_PGID ,
172: .Fn waitid
173: and
174: .Fn wait6
175: wait for the child process with a process group ID equal to
176: .Dv (pid_t)id .
177: .It
178: If
179: .Fa idtype
180: is
181: .Dv P_ALL ,
182: .Fn waitid
183: and
184: .Fn wait6
185: wait for any child process and the
186: .Dv id
187: is ignored.
188: .It
189: If
190: .Fa idtype
191: is
192: .Dv P_PID
193: or
194: .Dv P_PGID
195: and the
196: .Dv id
197: is zero,
198: .Fn waitid
199: and
200: .Fn wait6
201: wait for any child process in the same process group as the caller.
202: .El
203: .Pp
204: Non-standard identifier types supported by this
205: implementation of
206: .Fn waitid
207: and
208: .Fn wait6
209: are:
210: .Bl -tag -width P_JAILID
211: .It Dv P_UID
212: Wait for processes whose effective user ID is equal to
213: .Dv (uid_t) Fa id .
214: .It Dv P_GID
215: Wait for processes whose effective group ID is equal to
216: .Dv (gid_t) Fa id .
217: .It Dv P_SID
218: Wait for processes whose session ID is equal to
219: .Fa id .
220: .\" This is just how sessions work, not sure this needs to be documented here
221: If the child process started its own session,
222: its session ID will be the same as its process ID.
223: Otherwise the session ID of a child process will match the caller's session ID.
224: .\" .It Dv P_JAILID
225: .\" Waits for processes within a jail whose jail identifier is equal to
226: .\" .Fa id .
227: .El
228: .Pp
229: For the
230: .Fn waitpid
231: and
232: .Fn wait4
233: functions, the single
234: .Fa wpid
235: argument specifies the set of child processes for which to wait.
1.36 abhinav 236: The following symbolic constants are defined in
237: .In sys/wait.h
238: .Bd -literal -offset indent
239: #define WAIT_ANY (-1) /* any process */
240: #define WAIT_MYPGRP 0 /* any process in my process group */
241: .Ed
1.28 christos 242: .Bl -bullet -offset indent
243: .It
244: If
245: .Fa wpid
1.36 abhinav 246: is
247: .Dv WAIT_ANY ,
248: the call waits for any child process.
1.28 christos 249: .It
250: If
251: .Fa wpid
1.36 abhinav 252: is
253: .Dv WAIT_MYPGRP ,
1.28 christos 254: the call waits for any child process in the process group of the caller.
255: .It
256: If
257: .Fa wpid
258: is greater than zero, the call waits for the process with process ID
259: .Fa wpid .
260: .It
261: If
262: .Fa wpid
1.29 wiz 263: is less than \-1, the call waits for any process whose process group ID
1.28 christos 264: equals the absolute value of
265: .Fa wpid .
266: .El
267: .Pp
268: The
269: .Fa status
270: argument is defined below.
271: .Pp
272: The
273: .Fa options
274: argument contains the bitwise OR of any of the following options.
275: .Bl -tag -width WCONTINUED
1.33 christos 276: .It Dv WALLSIG
277: If this option is specified, the call will wait for all children regardless
278: of what exit signal they post.
279: .It Dv WALTSIG
280: If this option is specified, the call will wait only for processes that
281: are configured to post a signal other than
1.35 christos 282: .Dv SIGCHLD
283: when they exit.
284: If
285: .Dv WALTSIG
286: is not specified, the call will wait only for processes that
1.36 abhinav 287: are configured to post
1.35 christos 288: .Dv SIGCHLD .
1.28 christos 289: .It Dv WCONTINUED
290: Report the status of selected processes that
291: have continued from a job control stop by receiving a
292: .Dv SIGCONT
293: signal.
1.33 christos 294: .It Dv WEXITED
295: Report the status of selected processes which have terminated.
1.28 christos 296: This flag is implicitly set for the functions
297: .Fn wait ,
298: .Fn waitpid ,
299: .Fn wait3 ,
300: and
301: .Fn wait4 .
302: .br
303: For the
304: .Fn waitid
305: and
306: .Fn wait6
307: functions, the flag has to be explicitly included in
308: .Fa options
1.33 christos 309: if status reports from terminated processes are expected.
310: .It Dv WNOHANG
311: Do not block when
312: there are no processes wishing to report status.
313: .It Dv WNOWAIT
314: Keep the process whose status is returned in a waitable state.
315: The process may be waited for again after this call completes.
1.37 christos 316: .It Dv WNOZOMBIE
317: Exclude zombie processes from the child selection criteria.
1.33 christos 318: .It Dv WSTOPPED
319: An alias for
320: .Dv WUNTRACED .
321: .It Dv WTRAPPED
322: Report the status of selected processes which are being traced via
323: .Xr ptrace 2
324: and have trapped or reached a breakpoint.
1.28 christos 325: This flag is implicitly set for the functions
326: .Fn wait ,
327: .Fn waitpid ,
328: .Fn wait3 ,
329: and
330: .Fn wait4 .
331: .br
332: For the
333: .Fn waitid
334: and
335: .Fn wait6
336: functions, the flag has to be explicitly included in
337: .Fa options
1.33 christos 338: if status reports from trapped processes are expected.
339: .It Dv WUNTRACED
340: Report the status of selected processes which are stopped due to a
341: .Dv SIGTTIN , SIGTTOU , SIGTSTP ,
342: or
343: .Dv SIGSTOP
344: signal.
1.34 wiz 345: .It Dv __WALL
346: This is an alias for
347: .Dv WALLSIG .
348: It is provided for compatibility with the Linux
349: .Xr clone 2
350: API .
1.33 christos 351: .It Dv __WCLONE
352: This is an alias for
353: .Dv WALTSIG .
354: It is provided for compatibility with the Linux
355: .Xr clone 2
356: API.
1.28 christos 357: .El
358: .sp
359: For the
360: .Fn waitid
361: and
362: .Fn wait6
363: functions, at least one of the options
364: .Dv WEXITED ,
365: .Dv WUNTRACED ,
366: .Dv WSTOPPED ,
367: .Dv WTRAPPED ,
368: or
369: .Dv WCONTINUED
370: must be specified.
371: Otherwise there will be no events for the call to report.
372: To avoid hanging indefinitely in such a case these functions
1.29 wiz 373: return \-1 with
1.28 christos 374: .Dv errno
375: set to
376: .Dv EINVAL .
377: .Pp
378: If
379: .Fa rusage
1.29 wiz 380: is
381: .Pf non- Dv NULL ,
382: a summary of the resources used by the terminated
1.28 christos 383: process and all its children is returned.
384: .Pp
385: If
386: .Fa wrusage
1.29 wiz 387: is
388: .Pf non- Dv NULL ,
389: separate summaries are returned for the resources used
1.28 christos 390: by the terminated process and the resources used by all its children.
391: .Pp
392: If
393: .Fa infop
1.29 wiz 394: is
395: .Pf non- Dv NULL ,
396: a
1.28 christos 397: .Dv siginfo_t
398: structure is returned with the
399: .Fa si_signo
400: field set to
401: .Dv SIGCHLD
1.31 christos 402: and the
1.28 christos 403: .Fa si_pid
404: field set to the process ID of the process reporting status.
405: For the exited process, the
406: .Fa si_status
407: field of the
408: .Dv siginfo_t
409: structure contains the full 32 bit exit status passed to
410: .Xr _exit 2 ;
411: the
412: .Fa status
413: argument of other calls only returns 8 lowest bits of the exit status.
414: .Pp
415: When the
416: .Dv WNOHANG
417: option is specified and no processes
418: wish to report status,
419: .Fn waitid
420: sets the
421: .Fa si_signo
422: and
423: .Fa si_pid
424: fields in
425: .Fa infop
426: to zero.
427: Checking these fields is the only way to know if a status change was reported.
428: .Pp
1.1 cgd 429: When the
430: .Dv WNOHANG
431: option is specified and no processes
1.15 wiz 432: wish to report status,
1.1 cgd 433: .Fn wait4
1.15 wiz 434: returns a
1.1 cgd 435: process id
436: of 0.
437: .Pp
438: The
439: .Fn waitpid
440: call is identical to
441: .Fn wait4
442: with an
443: .Fa rusage
444: value of zero.
445: The older
446: .Fn wait3
447: call is the same as
448: .Fn wait4
449: with a
450: .Fa wpid
1.25 wiz 451: value of \-1.
1.1 cgd 452: .Pp
453: The following macros may be used to test the manner of exit of the process.
1.21 wiz 454: Note that these macros expect the
455: .Fa status
1.20 manu 456: value itself, not a pointer to the
1.21 wiz 457: .Fa status
1.20 manu 458: value.
1.1 cgd 459: One of the first three macros will evaluate to a non-zero (true) value:
460: .Bl -tag -width Ds
461: .It Fn WIFEXITED status
462: True if the process terminated normally by a call to
463: .Xr _exit 2
464: or
1.8 mikel 465: .Xr exit 3 .
1.1 cgd 466: .It Fn WIFSIGNALED status
467: True if the process terminated due to receipt of a signal.
468: .It Fn WIFSTOPPED status
469: True if the process has not terminated, but has stopped and can be restarted.
470: This macro can be true only if the wait call specified the
471: .Dv WUNTRACED
472: option
473: or if the child process is being traced (see
474: .Xr ptrace 2 ) .
1.30 christos 475: .It Fn WIFCONTINUED status
476: True if the process has not terminated, but has been continued via the
1.32 wiz 477: delivery of the
1.30 christos 478: .Dv SIGCONT
479: signal.
480: This macro can be true only if the wait call specified the
481: .Dv WCONTINUED
482: option.
1.1 cgd 483: .El
484: .Pp
485: Depending on the values of those macros, the following macros
486: produce the remaining status information about the child process:
487: .Bl -tag -width Ds
488: .It Fn WEXITSTATUS status
489: If
490: .Fn WIFEXITED status
491: is true, evaluates to the low-order 8 bits
492: of the argument passed to
493: .Xr _exit 2
494: or
1.8 mikel 495: .Xr exit 3
1.1 cgd 496: by the child.
497: .It Fn WTERMSIG status
498: If
499: .Fn WIFSIGNALED status
500: is true, evaluates to the number of the signal
501: that caused the termination of the process.
502: .It Fn WCOREDUMP status
503: If
504: .Fn WIFSIGNALED status
505: is true, evaluates as true if the termination
506: of the process was accompanied by the creation of a core file
507: containing an image of the process when the signal was received.
508: .It Fn WSTOPSIG status
509: If
510: .Fn WIFSTOPPED status
511: is true, evaluates to the number of the signal
512: that caused the process to stop.
513: .El
514: .Sh NOTES
515: See
516: .Xr sigaction 2
517: for a list of termination signals.
518: A status of 0 indicates normal termination.
519: .Pp
520: If a parent process terminates without
521: waiting for all of its child processes to terminate,
522: the remaining child processes are assigned the parent
523: process 1 ID (the init process ID).
524: .Pp
525: If a signal is caught while any of the
526: .Fn wait
527: calls is pending,
528: the call may be interrupted or restarted when the signal-catching routine
529: returns,
530: depending on the options in effect for the signal;
531: see
1.36 abhinav 532: .Xr siginterrupt 3 .
1.1 cgd 533: .Sh RETURN VALUES
534: If
535: .Fn wait
536: returns due to a stopped
537: or terminated child process, the process ID of the child
1.19 wiz 538: is returned to the calling process.
1.25 wiz 539: Otherwise, a value of \-1 is returned and
1.1 cgd 540: .Va errno
541: is set to indicate the error.
542: .Pp
543: If
1.28 christos 544: .Fn wait6 ,
1.1 cgd 545: .Fn wait4 ,
546: .Fn wait3
547: or
548: .Fn waitpid
549: returns due to a stopped
550: or terminated child process, the process ID of the child
551: is returned to the calling process.
552: If there are no children not previously awaited,
1.25 wiz 553: \-1 is returned with
1.1 cgd 554: .Va errno
555: set to
556: .Bq Er ECHILD .
557: Otherwise, if
558: .Dv WNOHANG
559: is specified and there are
1.19 wiz 560: no stopped or exited children, 0 is returned.
1.1 cgd 561: If an error is detected or a caught signal aborts the call,
1.25 wiz 562: a value of \-1 is returned and
1.1 cgd 563: .Va errno
564: is set to indicate the error.
1.28 christos 565: .Pp
566: If
567: .Fn waitid
568: returns because one or more processes have a state change to report,
569: 0 is returned.
570: If an error is detected,
571: a value of -1
572: is returned and
573: .Va errno
574: is set to indicate the error.
575: If
576: .Dv WNOHANG
577: is specified and there are
578: no stopped, continued or exited children,
579: 0 is returned.
580: The
581: .Fa si_signo
582: and
583: .Fa si_pid
584: fields of
585: .Fa infop
586: must be checked against zero to determine if a process reported status.
1.1 cgd 587: .Sh ERRORS
1.10 lukem 588: .Fn wait
1.1 cgd 589: will fail and return immediately if:
590: .Bl -tag -width Er
591: .It Bq Er ECHILD
1.29 wiz 592: The calling process has no existing unwaited-for child processes; or
593: no status from the terminated child process is available
1.28 christos 594: because the calling process has asked the system to discard
595: such status by ignoring the signal
596: .Dv SIGCHLD
597: or setting the flag
598: .Dv SA_NOCLDWAIT
599: for that signal.
1.1 cgd 600: .It Bq Er EFAULT
601: The
602: .Fa status
603: or
604: .Fa rusage
605: arguments point to an illegal address.
606: (May not be detected before exit of a child process.)
607: .It Bq Er EINTR
608: The call was interrupted by a caught signal,
609: or the signal did not have the
610: .Dv SA_RESTART
611: flag set.
1.7 mikel 612: .El
613: .Pp
614: In addition,
1.28 christos 615: .Fn wait6 ,
1.7 mikel 616: .Fn wait3 ,
617: .Fn wait4 ,
1.28 christos 618: .Fn waitid ,
1.7 mikel 619: and
620: .Fn waitpid
621: will fail and return immediately if:
622: .Bl -tag -width Er
623: .It Bq Er EINVAL
624: An invalid value was specified for
625: .Fa options .
1.1 cgd 626: .El
1.16 wiz 627: .Sh SEE ALSO
628: .Xr _exit 2 ,
1.39 wiz 629: .Xr fork 2 ,
1.28 christos 630: .Xr ptrace 2 ,
631: .Xr sigaction 2 ,
1.36 abhinav 632: .Xr siginfo 2 ,
633: .Xr exit 3 ,
634: .Xr siginterrupt 3
1.1 cgd 635: .Sh STANDARDS
636: The
637: .Fn wait
638: and
639: .Fn waitpid
1.9 kleink 640: functions conform to
641: .St -p1003.1-90 ;
642: the
1.28 christos 643: .Fn waitid
1.29 wiz 644: function conforms to
1.28 christos 645: .St -p1003.1-2004 ;
646: the
1.9 kleink 647: .Fn wait3
648: function conforms to
649: .St -xpg4 ;
1.1 cgd 650: .Fn wait4
1.9 kleink 651: is an extension.
1.1 cgd 652: The
653: .Fn WCOREDUMP
654: macro
655: and the ability to restart a pending
656: .Fn wait
657: call are extensions to the POSIX interface.
658: .Sh HISTORY
659: A
1.4 jtc 660: .Fn wait
1.15 wiz 661: function call appeared in
1.39.16.1! martin 662: .At v1 .
CVSweb <webmaster@jp.NetBSD.org>
![[BACK]](/icons/back.gif){kind=icon}
Return to wait.2 CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [cvs.NetBSD.org] / src / lib / libc / sys