[BACK]Return to wait.2 CVS log [TXT][DIR] Up to [cvs.NetBSD.org] / src / lib / libc / sys

Annotation of src/lib/libc/sys/wait.2, Revision 1.2

1.1       cgd         1: .\" Copyright (c) 1980, 1991 Regents of the University of California.
                      2: .\" All rights reserved.
                      3: .\"
                      4: .\" Redistribution and use in source and binary forms, with or without
                      5: .\" modification, are permitted provided that the following conditions
                      6: .\" are met:
                      7: .\" 1. Redistributions of source code must retain the above copyright
                      8: .\"    notice, this list of conditions and the following disclaimer.
                      9: .\" 2. Redistributions in binary form must reproduce the above copyright
                     10: .\"    notice, this list of conditions and the following disclaimer in the
                     11: .\"    documentation and/or other materials provided with the distribution.
                     12: .\" 3. All advertising materials mentioning features or use of this software
                     13: .\"    must display the following acknowledgement:
                     14: .\"    This product includes software developed by the University of
                     15: .\"    California, Berkeley and its contributors.
                     16: .\" 4. Neither the name of the University nor the names of its contributors
                     17: .\"    may be used to endorse or promote products derived from this software
                     18: .\"    without specific prior written permission.
                     19: .\"
                     20: .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
                     21: .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
                     22: .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
                     23: .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
                     24: .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
                     25: .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
                     26: .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
                     27: .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
                     28: .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
                     29: .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
                     30: .\" SUCH DAMAGE.
                     31: .\"
1.2     ! mycroft    32: .\"     from: @(#)wait.2       6.5 (Berkeley) 3/10/91
        !            33: .\"    $Id: $
1.1       cgd        34: .\"
                     35: .Dd March 10, 1991
                     36: .Dt WAIT 2
                     37: .Os BSD 4
                     38: .Sh NAME
                     39: .Nm wait ,
                     40: .Nm waitpid ,
                     41: .Nm wait4 ,
                     42: .Nm wait3
                     43: .Nd wait for process terminatation
                     44: .Sh SYNOPSIS
                     45: .Fd #include <sys/types.h>
                     46: .Fd #include <sys/wait.h>
                     47: .Ft pid_t
                     48: .Fn wait "int *status"
                     49: .Fd #include <sys/time.h>
                     50: .Fd #include <sys/resource.h>
                     51: .Ft pid_t
                     52: .Fn waitpid "pid_t wpid" "int *status" "int options"
                     53: .Ft pid_t
                     54: .Fn wait3 "int *status" "int options" "struct rusage *rusage"
                     55: .Ft pid_t
                     56: .Fn wait4 "pid_t wpid" "int *status" "int options" "struct rusage *rusage"
                     57: .Sh DESCRIPTION
                     58: The
                     59: .Fn wait
                     60: function suspends execution of its calling process until
                     61: .Fa status
                     62: information is available for a terminated child process,
                     63: or a signal is received.
                     64: On return from a successful
                     65: .Fn wait
                     66: call,
                     67: the
                     68: .Fa status
                     69: area contains termination information about the process that exited
                     70: as defined below.
                     71: .Pp
                     72: The
                     73: .Fn wait4
                     74: call provides a more general interface for programs
                     75: that need to wait for certain child processes,
                     76: that need resource utilization statistics accummulated by child processes,
                     77: or that require options.
                     78: The other wait functions are implemented using
                     79: .Fn wait4 .
                     80: .Pp
                     81: The
                     82: .Fa wpid
                     83: parameter specifies the set of child processes for which to wait.
                     84: If
                     85: .Fa wpid
                     86: is -1, the call waits for any child process.
                     87: If
                     88: .Fa wpid
                     89: is 0,
                     90: the call waits for any child process in the process group of the caller.
                     91: If
                     92: .Fa wpid
                     93: is greater than zero, the call waits for the process with process id
                     94: .Fa wpid .
                     95: If
                     96: .Fa wpid
                     97: is less than -1, the call waits for any process whose process group id
                     98: equals the absolute value of
                     99: .Fa wpid .
                    100: .Pp
                    101: The
                    102: .Fa status
                    103: parameter is defined below.  The
                    104: .Fa options
                    105: parameter contains the bitwise OR of any of the following options.
                    106: The
                    107: .Dv WNOHANG
                    108: option
                    109: is used to indicate that the call should not block if
                    110: there are no processes that wish to report status.
                    111: If the
                    112: .Dv WUNTRACED
                    113: option is set,
                    114: children of the current process that are stopped
                    115: due to a
                    116: .Dv SIGTTIN , SIGTTOU , SIGTSTP ,
                    117: or
                    118: .Dv SIGSTOP
                    119: signal also have
                    120: their status reported.
                    121: .Pp
                    122: If
                    123: .Fa rusage
                    124: is non-zero, a summary of the resources used by the terminated
                    125: process and all its
                    126: children is returned (this information is currently not available
                    127: for stopped processes).
                    128: .Pp
                    129: When the
                    130: .Dv WNOHANG
                    131: option is specified and no processes
                    132: wish to report status,
                    133: .Fn wait4
                    134: returns a
                    135: process id
                    136: of 0.
                    137: .Pp
                    138: The
                    139: .Fn waitpid
                    140: call is identical to
                    141: .Fn wait4
                    142: with an
                    143: .Fa rusage
                    144: value of zero.
                    145: The older
                    146: .Fn wait3
                    147: call is the same as
                    148: .Fn wait4
                    149: with a
                    150: .Fa wpid
                    151: value of -1.
                    152: .Pp
                    153: The following macros may be used to test the manner of exit of the process.
                    154: One of the first three macros will evaluate to a non-zero (true) value:
                    155: .Bl -tag -width Ds
                    156: .It Fn WIFEXITED status
                    157: True if the process terminated normally by a call to
                    158: .Xr _exit 2
                    159: or
                    160: .Xr exit 2 .
                    161: .It Fn WIFSIGNALED status
                    162: True if the process terminated due to receipt of a signal.
                    163: .It Fn WIFSTOPPED status
                    164: True if the process has not terminated, but has stopped and can be restarted.
                    165: This macro can be true only if the wait call specified the
                    166: .Dv WUNTRACED
                    167: option
                    168: or if the child process is being traced (see
                    169: .Xr ptrace 2 ) .
                    170: .El
                    171: .Pp
                    172: Depending on the values of those macros, the following macros
                    173: produce the remaining status information about the child process:
                    174: .Bl -tag -width Ds
                    175: .It Fn WEXITSTATUS status
                    176: If
                    177: .Fn WIFEXITED status
                    178: is true, evaluates to the low-order 8 bits
                    179: of the argument passed to
                    180: .Xr _exit 2
                    181: or
                    182: .Xr exit 2
                    183: by the child.
                    184: .It Fn WTERMSIG status
                    185: If
                    186: .Fn WIFSIGNALED status
                    187: is true, evaluates to the number of the signal
                    188: that caused the termination of the process.
                    189: .It Fn WCOREDUMP status
                    190: If
                    191: .Fn WIFSIGNALED status
                    192: is true, evaluates as true if the termination
                    193: of the process was accompanied by the creation of a core file
                    194: containing an image of the process when the signal was received.
                    195: .It Fn WSTOPSIG status
                    196: If
                    197: .Fn WIFSTOPPED status
                    198: is true, evaluates to the number of the signal
                    199: that caused the process to stop.
                    200: .El
                    201: .Sh NOTES
                    202: See
                    203: .Xr sigaction 2
                    204: for a list of termination signals.
                    205: A status of 0 indicates normal termination.
                    206: .Pp
                    207: If a parent process terminates without
                    208: waiting for all of its child processes to terminate,
                    209: the remaining child processes are assigned the parent
                    210: process 1 ID (the init process ID).
                    211: .Pp
                    212: If a signal is caught while any of the
                    213: .Fn wait
                    214: calls is pending,
                    215: the call may be interrupted or restarted when the signal-catching routine
                    216: returns,
                    217: depending on the options in effect for the signal;
                    218: see
                    219: .Xr intro 2 ,
                    220: System call restart.
                    221: .Sh RETURN VALUES
                    222: If
                    223: .Fn wait
                    224: returns due to a stopped
                    225: or terminated child process, the process ID of the child
                    226: is returned to the calling process.  Otherwise, a value of -1
                    227: is returned and
                    228: .Va errno
                    229: is set to indicate the error.
                    230: .Pp
                    231: If
                    232: .Fn wait4 ,
                    233: .Fn wait3
                    234: or
                    235: .Fn waitpid
                    236: returns due to a stopped
                    237: or terminated child process, the process ID of the child
                    238: is returned to the calling process.
                    239: If there are no children not previously awaited,
                    240: -1 is returned with
                    241: .Va errno
                    242: set to
                    243: .Bq Er ECHILD .
                    244: Otherwise, if
                    245: .Dv WNOHANG
                    246: is specified and there are
                    247: no stopped or exited children,
                    248: 0 is returned.
                    249: If an error is detected or a caught signal aborts the call,
                    250: a value of -1
                    251: is returned and
                    252: .Va errno
                    253: is set to indicate the error.
                    254: .Sh ERRORS
                    255: .Fn Wait
                    256: will fail and return immediately if:
                    257: .Bl -tag -width Er
                    258: .It Bq Er ECHILD
                    259: The calling process has no existing unwaited-for
                    260: child processes.
                    261: .It Bq Er EFAULT
                    262: The
                    263: .Fa status
                    264: or
                    265: .Fa rusage
                    266: arguments point to an illegal address.
                    267: (May not be detected before exit of a child process.)
                    268: .It Bq Er EINTR
                    269: The call was interrupted by a caught signal,
                    270: or the signal did not have the
                    271: .Dv SA_RESTART
                    272: flag set.
                    273: .El
                    274: .Sh STANDARDS
                    275: The
                    276: .Fn wait
                    277: and
                    278: .Fn waitpid
                    279: functions are defined by POSIX;
                    280: .Fn wait4
                    281: and
                    282: .Fn wait3
                    283: are not specified by POSIX.
                    284: The
                    285: .Fn WCOREDUMP
                    286: macro
                    287: and the ability to restart a pending
                    288: .Fn wait
                    289: call are extensions to the POSIX interface.
                    290: .Sh SEE ALSO
                    291: .Xr exit 2 ,
                    292: .Xr sigaction 2
                    293: .Sh HISTORY
                    294: A
                    295: .Nm
                    296: function call appeared in Version 6 AT&T UNIX.

CVSweb <webmaster@jp.NetBSD.org>