man/man2/wait.2

   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).