| 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.2 (Berkeley) 6/30/85
|
|---|
| 6 | .\"
|
|---|
| 7 | .TH WAIT 2 "June 30, 1985"
|
|---|
| 8 | .UC 4
|
|---|
| 9 | .SH NAME
|
|---|
| 10 | wait, waitpid \- wait for process to terminate
|
|---|
| 11 | .SH SYNOPSIS
|
|---|
| 12 | .ft B
|
|---|
| 13 | .nf
|
|---|
| 14 | #include <sys/types.h>
|
|---|
| 15 | #include <sys/wait.h>
|
|---|
| 16 |
|
|---|
| 17 | pid_t wait(int *\fIstatus\fP)
|
|---|
| 18 | pid_t waitpid(pid_t \fIpid\fP, int *\fIstatus\fP, int \fIoptions\fP)
|
|---|
| 19 | .fi
|
|---|
| 20 | .SH DESCRIPTION
|
|---|
| 21 | .B Wait
|
|---|
| 22 | causes its caller to delay until a signal is received or
|
|---|
| 23 | one of its child
|
|---|
| 24 | processes terminates.
|
|---|
| 25 | If any child has died since the last
|
|---|
| 26 | .BR wait ,
|
|---|
| 27 | return is immediate, returning the process id and
|
|---|
| 28 | exit status of one of the terminated
|
|---|
| 29 | children.
|
|---|
| 30 | If there are no children, return is immediate with
|
|---|
| 31 | the value \-1 returned.
|
|---|
| 32 | .PP
|
|---|
| 33 | On return from a successful
|
|---|
| 34 | .B wait
|
|---|
| 35 | call,
|
|---|
| 36 | .I status
|
|---|
| 37 | is nonzero, and the high byte of
|
|---|
| 38 | .I status
|
|---|
| 39 | contains the low byte of the argument to
|
|---|
| 40 | .B exit
|
|---|
| 41 | supplied by the child process;
|
|---|
| 42 | the low byte of
|
|---|
| 43 | .I status
|
|---|
| 44 | contains the termination status of the process.
|
|---|
| 45 | A more precise definition of the
|
|---|
| 46 | .I status
|
|---|
| 47 | word is given in
|
|---|
| 48 | .RI < sys/wait.h >.
|
|---|
| 49 | .B Wait
|
|---|
| 50 | can be called with a null pointer argument to indicate that no status need
|
|---|
| 51 | be returned.
|
|---|
| 52 | .PP
|
|---|
| 53 | .B Waitpid
|
|---|
| 54 | provides an alternate interface for programs
|
|---|
| 55 | that must not block when collecting the status
|
|---|
| 56 | of child processes, or that wish to wait for
|
|---|
| 57 | one particular child. The pid parameter is
|
|---|
| 58 | the process ID of the child to wait for, \-1
|
|---|
| 59 | for any child. The
|
|---|
| 60 | .I status
|
|---|
| 61 | parameter is defined as above. The
|
|---|
| 62 | .I options
|
|---|
| 63 | parameter is used to indicate the call should not block if
|
|---|
| 64 | there are no processes that wish to report status (WNOHANG),
|
|---|
| 65 | and/or that children of the current process that are stopped
|
|---|
| 66 | due to a SIGTTIN, SIGTTOU, SIGTSTP, or SIGSTOP signal should also have
|
|---|
| 67 | their status reported (WUNTRACED). (Job control is not implemented for
|
|---|
| 68 | MINIX 3, but these symbols and signals are.)
|
|---|
| 69 | .PP
|
|---|
| 70 | When the WNOHANG option is specified and no processes
|
|---|
| 71 | wish to report status,
|
|---|
| 72 | .B waitpid
|
|---|
| 73 | either returns 0 under some implementations, or \-1 with
|
|---|
| 74 | .B errno
|
|---|
| 75 | set to
|
|---|
| 76 | .B EAGAIN
|
|---|
| 77 | under others.
|
|---|
| 78 | (Under MINIX 3 it returns 0.)
|
|---|
| 79 | The WNOHANG and WUNTRACED options may be combined by
|
|---|
| 80 | .IR or 'ing
|
|---|
| 81 | the two values.
|
|---|
| 82 | .SH NOTES
|
|---|
| 83 | The call
|
|---|
| 84 | .BI "wait(&" status ")"
|
|---|
| 85 | is equivalent to
|
|---|
| 86 | .BI "waitpid(\-1, &" status ", 0)\fR."
|
|---|
| 87 | .PP
|
|---|
| 88 | See
|
|---|
| 89 | .BR sigaction (2)
|
|---|
| 90 | for a list of termination statuses (signals);
|
|---|
| 91 | 0 status indicates normal termination.
|
|---|
| 92 | A special status (0177) is returned for a stopped process
|
|---|
| 93 | that has not terminated and can be restarted;
|
|---|
| 94 | see
|
|---|
| 95 | .BR ptrace (2).
|
|---|
| 96 | If the 0200 bit of the termination status
|
|---|
| 97 | is set,
|
|---|
| 98 | a core image of the process was produced
|
|---|
| 99 | by the system.
|
|---|
| 100 | .PP
|
|---|
| 101 | If the parent process terminates without
|
|---|
| 102 | waiting on its children,
|
|---|
| 103 | the initialization process
|
|---|
| 104 | (process ID = 1)
|
|---|
| 105 | inherits the children.
|
|---|
| 106 | .PP
|
|---|
| 107 | .I <sys/wait.h>
|
|---|
| 108 | defines a number of macros that operate on a status word:
|
|---|
| 109 | .TP 5
|
|---|
| 110 | .BI "WIFEXITED(" status ")"
|
|---|
| 111 | True if normal exit.
|
|---|
| 112 | .TP 5
|
|---|
| 113 | .BI "WEXITSTATUS(" status ")"
|
|---|
| 114 | Exit status if the process returned by a normal exit, zero otherwise.
|
|---|
| 115 | .TP 5
|
|---|
| 116 | .BI "WTERMSIG(" status ")"
|
|---|
| 117 | Signal number if the process died by a signal, zero otherwise.
|
|---|
| 118 | .TP 5
|
|---|
| 119 | .BI "WIFSIGNALED(" status ")"
|
|---|
| 120 | True if the process died by a signal.
|
|---|
| 121 | .TP 5
|
|---|
| 122 | .BI "WIFSTOPPED(" status ")"
|
|---|
| 123 | True if the process is stopped. (Never true under MINIX 3.)
|
|---|
| 124 | .TP 5
|
|---|
| 125 | .BI "WSTOPSIG(" status ")"
|
|---|
| 126 | Signal number of the signal that stopped the process.
|
|---|
| 127 | .SH "RETURN VALUE
|
|---|
| 128 | If \fBwait\fP returns due to a stopped
|
|---|
| 129 | or terminated child process, the process ID of the child
|
|---|
| 130 | is returned to the calling process. Otherwise, a value of \-1
|
|---|
| 131 | is returned and \fBerrno\fP is set to indicate the error.
|
|---|
| 132 | .PP
|
|---|
| 133 | .B Waitpid
|
|---|
| 134 | returns \-1 if there are no children not previously waited for or if
|
|---|
| 135 | the process that it wants to wait for doesn't exist.
|
|---|
| 136 | .PP
|
|---|
| 137 | .B Waitpid
|
|---|
| 138 | returns 0 if WNOHANG is specified and there are no stopped or exited
|
|---|
| 139 | children. (Under other implementations it may return \-1 instead. Portable
|
|---|
| 140 | code should test for both possibilities.)
|
|---|
| 141 | .SH ERRORS
|
|---|
| 142 | .B Wait
|
|---|
| 143 | will fail and return immediately if one or more of the following
|
|---|
| 144 | are true:
|
|---|
| 145 | .TP 15
|
|---|
| 146 | [ECHILD]
|
|---|
| 147 | The calling process has no existing unwaited-for
|
|---|
| 148 | child processes.
|
|---|
| 149 | .TP 15
|
|---|
| 150 | [EFAULT]
|
|---|
| 151 | The \fIstatus\fP argument points to an illegal address.
|
|---|
| 152 | .TP 15
|
|---|
| 153 | [EAGAIN]
|
|---|
| 154 | .B Waitpid
|
|---|
| 155 | is called with the WNOHANG option and no child has exited yet. (Not under
|
|---|
| 156 | MINIX 3, it'll return 0 in this case and leave
|
|---|
| 157 | .B errno
|
|---|
| 158 | alone.)
|
|---|
| 159 | .SH "SEE ALSO"
|
|---|
| 160 | .BR execve (2),
|
|---|
| 161 | .BR exit (2),
|
|---|
| 162 | .BR sigaction (2).
|
|---|
