Return to wait.2 CVS log

Up to [CSRG BSD Unix] / 43BSDReno / lib / libc / sys

Annotation of 43BSDReno/lib/libc/sys/wait.2, revision 1.1

1.1     ! root        1: .\" Copyright (c) 1980 Regents of the University of California.
        !             2: .\" All rights reserved.  The Berkeley software License Agreement
        !             3: .\" specifies the terms and conditions for redistribution.
        !             4: .\"
        !             5: .\"    @(#)wait.2      6.3 (Berkeley) 8/14/89
        !             6: .\"
        !             7: .TH WAIT 2 "August 14, 1989"
        !             8: .UC 4
        !             9: .SH NAME
        !            10: wait, waitpid, wait4, wait3 \- wait for process to terminate
        !            11: .SH SYNOPSIS
        !            12: .ft B
        !            13: .nf
        !            14: #include <sys/types.h>
        !            15: #include <sys/wait.h>
        !            16: .PP
        !            17: .ft B
        !            18: pid = wait(status)
        !            19: pid_t pid;
        !            20: int *status;
        !            21: .PP
        !            22: .ft B
        !            23: pid = waitpid(wpid, status, options)
        !            24: pid_t pid, wpid;
        !            25: int *status;
        !            26: int options;
        !            27: .PP
        !            28: .ft B
        !            29: #include <sys/time.h>
        !            30: #include <sys/resource.h>
        !            31: .PP
        !            32: .ft B
        !            33: pid = wait4(wpid, status, options, rusage)
        !            34: pid_t pid, wpid;
        !            35: int *status;
        !            36: int options;
        !            37: struct rusage *rusage;
        !            38: .PP
        !            39: .ft B
        !            40: pid = wait3(status, options, rusage)
        !            41: pid_t pid;
        !            42: int *status;
        !            43: int options;
        !            44: struct rusage *rusage;
        !            45: .fi
        !            46: .SH DESCRIPTION
        !            47: .I Wait
        !            48: causes its caller to delay until a signal is received or
        !            49: one of its child
        !            50: processes terminates.
        !            51: If any child has died since the last
        !            52: .IR wait ,
        !            53: return is immediate, returning the process id and
        !            54: exit status of one of the terminated
        !            55: children.
        !            56: If there are no children, return is immediate with
        !            57: the value \-1 returned.
        !            58: .PP
        !            59: On return from a successful 
        !            60: .I wait
        !            61: call, 
        !            62: the
        !            63: .I status
        !            64: area contains termination information about the process that exited
        !            65: as defined below.
        !            66: .PP
        !            67: The
        !            68: .I wait4
        !            69: call provides a more general interface for programs
        !            70: that wish to wait for certain child processes,
        !            71: that wish resource utilization statistics accummulated by child processes,
        !            72: or that require options.
        !            73: The other wait functions are implemented using
        !            74: .IR wait4 .
        !            75: .PP
        !            76: The
        !            77: .I wpid
        !            78: parameter specifies the set of child processes for which to wait.
        !            79: If
        !            80: .I wpid
        !            81: is \-1, the call waits for any child process.
        !            82: If
        !            83: .I wpid
        !            84: is 0,
        !            85: the call waits for any child process in the process group of the caller.
        !            86: If
        !            87: .I wpid
        !            88: is greater than zero, the call waits for the process with process id
        !            89: .IR wpid .
        !            90: If
        !            91: .I wpid
        !            92: is less than \-1, the call waits for any process whose process group id
        !            93: equals the absolute value of
        !            94: .IR wpid .
        !            95: .PP
        !            96: The
        !            97: .I status
        !            98: parameter is defined below.  The
        !            99: .I options
        !           100: parameter contains the bitwise OR of any of the following options.
        !           101: The WNOHANG option
        !           102: is used to indicate that the call should not block if
        !           103: there are no processes that wish to report status.
        !           104: If the WUNTRACED option is set,
        !           105: children of the current process that are stopped
        !           106: due to a SIGTTIN, SIGTTOU, SIGTSTP, or SIGSTOP signal also have
        !           107: their status reported.
        !           108: .PP
        !           109: If
        !           110: .I rusage
        !           111: is non-zero, a summary of the resources used by the terminated
        !           112: process and all its
        !           113: children is returned (this information is currently not available
        !           114: for stopped processes).
        !           115: .PP
        !           116: When the WNOHANG option is specified and no processes
        !           117: wish to report status, 
        !           118: .I wait4
        !           119: returns a 
        !           120: .I pid
        !           121: of 0.
        !           122: .PP
        !           123: The
        !           124: .I waitpid
        !           125: call is identical to
        !           126: .I wait4
        !           127: with an
        !           128: .I rusage
        !           129: value of zero.
        !           130: The older
        !           131: .I wait3
        !           132: call is the same as
        !           133: .I wait4
        !           134: with a
        !           135: .I wpid
        !           136: value of \-1.
        !           137: .PP
        !           138: The following macros may be used to test the manner of exit of the process.
        !           139: One of the first three macros will evaluate to a non-zero (true) value:
        !           140: .IP WIFEXITED(status)
        !           141: True if the process terminated normally by a call to
        !           142: .IR _exit (2)
        !           143: or
        !           144: .IR exit (2).
        !           145: .IP WIFSIGNALED(status)
        !           146: True if the process terminated due to receipt of a signal.
        !           147: .IP WIFSTOPPED(status)
        !           148: True if the process has not terminated, but has stopped and can be restarted.
        !           149: This macro can be true only if the wait call specified the
        !           150: WUNTRACED
        !           151: option
        !           152: or if the child process is being traced (see
        !           153: .IR ptrace (2)).
        !           154: .LP
        !           155: Depending on the values of those macros, the following macros
        !           156: produce the remaining status information about the child process:
        !           157: .IP WEXITSTATUS(status)
        !           158: If WIFEXITED(status) is true, evaluates to the low-order 8 bits
        !           159: of the argument passed to
        !           160: .IR _exit (2)
        !           161: or
        !           162: .IR exit (2)
        !           163: by the child.
        !           164: .IP WTERMSIG(status)
        !           165: If WIFSIGNALED(status) is true, evaluates to the number of the signal
        !           166: that caused the termination of the process.
        !           167: .IP WCOREDUMP(status)
        !           168: If WIFSIGNALED(status) is true, evaluates as true if the termination
        !           169: of the process was accompanied by the creation of a core file
        !           170: containing an image of the process when the signal was received.
        !           171: .IP WSTOPSIG(status)
        !           172: If WIFSTOPPED(status) is true, evaluates to the number of the signal
        !           173: that caused the process to stop.
        !           174: .SH NOTES
        !           175: See
        !           176: .IR sigaction (2)
        !           177: for a list of termination signals.
        !           178: A status of 0 indicates normal termination.
        !           179: .PP
        !           180: If the parent process terminates without
        !           181: waiting on its children,
        !           182: the initialization process
        !           183: (process ID = 1)
        !           184: inherits the children.
        !           185: .PP
        !           186: If a signal is caught while any of the
        !           187: .I wait
        !           188: calls is pending,
        !           189: the call may be interrupted or restarted when the signal-catching routine
        !           190: returns,
        !           191: depending on the options in effect for the signal;
        !           192: see
        !           193: .IR intro (2),
        !           194: System call restart.
        !           195: .SH "RETURN VALUE
        !           196: If \fIwait\fP returns due to a stopped
        !           197: or terminated child process, the process ID of the child
        !           198: is returned to the calling process.  Otherwise, a value of \-1
        !           199: is returned and \fIerrno\fP is set to indicate the error.
        !           200: .PP
        !           201: If
        !           202: .IR wait4 ,
        !           203: .I wait3
        !           204: or
        !           205: .I waitpid
        !           206: returns due to a stopped
        !           207: or terminated child process, the process ID of the child
        !           208: is returned to the calling process.
        !           209: If there are no children not previously awaited,
        !           210: \-1 is returned with
        !           211: .I errno
        !           212: set to [ECHILD].
        !           213: Otherwise, if WNOHANG is specified and there are
        !           214: no stopped or exited children,
        !           215: 0 is returned.
        !           216: If an error is detected or a caught signal aborts the call,
        !           217: a value of \-1
        !           218: is returned and \fIerrno\fP is set to indicate the error.
        !           219: .SH ERRORS
        !           220: .I Wait
        !           221: will fail and return immediately if one or more of the following
        !           222: are true:
        !           223: .TP 15
        !           224: [ECHILD]
        !           225: The calling process has no existing unwaited-for
        !           226: child processes.
        !           227: .TP 15
        !           228: [EFAULT]
        !           229: The \fIstatus\fP or \fIrusage\fP arguments point to an illegal address.
        !           230: (May not be detected before exit of a child process.)
        !           231: .TP 15
        !           232: [EINTR]
        !           233: The call was interrupted by a caught signal,
        !           234: or the signal did not have the SA_RESTART flag set.
        !           235: .SH STANDARDS
        !           236: The
        !           237: .I wait
        !           238: and
        !           239: .I waitpid
        !           240: functions are defined by POSIX;
        !           241: .I wait4
        !           242: and
        !           243: .I wait3
        !           244: are not specified by POSIX.
        !           245: The WCOREDUMP macro
        !           246: and the ability to restart a pending
        !           247: .I wait
        !           248: call are extensions to the POSIX interface.
        !           249: .SH "SEE ALSO"
        !           250: exit(2), sigaction(2)

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.