2fe8fb192f
There is important information about booting non-ack images in docs/UPDATING. ack/aout-format images can't be built any more, and booting clang/ELF-format ones is a little different. Updating to the new boot monitor is recommended. Changes in this commit: . drop boot monitor -> allowing dropping ack support . facility to copy ELF boot files to /boot so that old boot monitor can still boot fairly easily, see UPDATING . no more ack-format libraries -> single-case libraries . some cleanup of OBJECT_FMT, COMPILER_TYPE, etc cases . drop several ack toolchain commands, but not all support commands (e.g. aal is gone but acksize is not yet). . a few libc files moved to netbsd libc dir . new /bin/date as minix date used code in libc/ . test compile fix . harmonize includes . /usr/lib is no longer special: without ack, /usr/lib plays no kind of special bootstrapping role any more and bootstrapping is done exclusively through packages, so releases depend even less on the state of the machine making them now. . rename nbsd_lib* to lib* . reduce mtree
335 lines
8.4 KiB
Groff
335 lines
8.4 KiB
Groff
.\" $NetBSD: wait.2,v 1.27 2010/04/03 15:43:46 jruoho Exp $
|
|
.\"
|
|
.\" Copyright (c) 1980, 1991, 1993, 1994
|
|
.\" The Regents of the University of California. All rights reserved.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\" 3. Neither the name of the University nor the names of its contributors
|
|
.\" may be used to endorse or promote products derived from this software
|
|
.\" without specific prior written permission.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
|
|
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
|
|
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
|
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
|
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
|
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
|
.\" SUCH DAMAGE.
|
|
.\"
|
|
.\" @(#)wait.2 8.2 (Berkeley) 4/19/94
|
|
.\"
|
|
.Dd April 3, 2010
|
|
.Dt WAIT 2
|
|
.Os
|
|
.Sh NAME
|
|
.Nm wait ,
|
|
.Nm waitpid ,
|
|
.Nm wait4 ,
|
|
.Nm wait3
|
|
.Nd wait for process termination
|
|
.Sh LIBRARY
|
|
.Lb libc
|
|
.Sh SYNOPSIS
|
|
.In sys/wait.h
|
|
.Ft pid_t
|
|
.Fn wait "int *status"
|
|
.Ft pid_t
|
|
.Fn waitpid "pid_t wpid" "int *status" "int options"
|
|
.In sys/resource.h
|
|
.Ft pid_t
|
|
.Fn wait3 "int *status" "int options" "struct rusage *rusage"
|
|
.Ft pid_t
|
|
.Fn wait4 "pid_t wpid" "int *status" "int options" "struct rusage *rusage"
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Fn wait
|
|
function suspends execution of its calling process until
|
|
.Fa status
|
|
information is available for a terminated child process,
|
|
or a signal is received.
|
|
On return from a successful
|
|
.Fn wait
|
|
call,
|
|
the
|
|
.Fa status
|
|
area contains termination information about the process that exited
|
|
as defined below.
|
|
.Pp
|
|
The
|
|
.Fn wait4
|
|
call provides a more general interface for programs
|
|
that need to wait for certain child processes,
|
|
that need resource utilization statistics accumulated by child processes,
|
|
or that require options.
|
|
The other wait functions are implemented using
|
|
.Fn wait4 .
|
|
.Pp
|
|
The
|
|
.Fa wpid
|
|
parameter specifies the set of child processes for which to wait.
|
|
If
|
|
.Fa wpid
|
|
is \-1, the call waits for any child process.
|
|
If
|
|
.Fa wpid
|
|
is 0,
|
|
the call waits for any child process in the process group of the caller.
|
|
If
|
|
.Fa wpid
|
|
is greater than zero, the call waits for the process with process id
|
|
.Fa wpid .
|
|
If
|
|
.Fa wpid
|
|
is less than \-1, the call waits for any process whose process group id
|
|
equals the absolute value of
|
|
.Fa wpid .
|
|
.Pp
|
|
The
|
|
.Fa status
|
|
parameter is defined below.
|
|
.Pp
|
|
The
|
|
.Fa options
|
|
parameter contains the bitwise OR of any of the following options:
|
|
.Bl -tag -width WUNTRACED
|
|
.It Dv WNOHANG
|
|
This option is used to indicate that the call should not block if
|
|
there are no processes that wish to report status.
|
|
.It Dv WUNTRACED
|
|
If this option is set, children of the current process that are stopped
|
|
due to a
|
|
.Dv SIGTTIN , SIGTTOU , SIGTSTP ,
|
|
or
|
|
.Dv SIGSTOP
|
|
signal also have their status reported.
|
|
.It Dv WALTSIG
|
|
If this option is specified, the call will wait only for processes that
|
|
are configured to post a signal other than
|
|
.Dv SIGCHLD
|
|
when they exit.
|
|
If
|
|
.Dv WALTSIG
|
|
is not specified, the call will wait only for processes that
|
|
are configured to post
|
|
.Dv SIGCHLD .
|
|
.It Dv __WCLONE
|
|
This is an alias for
|
|
.Dv WALTSIG .
|
|
It is provided for compatibility with the Linux
|
|
.Xr clone 2
|
|
API.
|
|
.It Dv WALLSIG
|
|
If this option is specified, the call will wait for all children regardless
|
|
of what exit signal they post.
|
|
.It Dv __WALL
|
|
This is an alias for
|
|
.Dv WALLSIG .
|
|
It is provided for compatibility with the Linux
|
|
.Xr clone 2
|
|
API .
|
|
.El
|
|
.Pp
|
|
If
|
|
.Fa rusage
|
|
is non-zero, a summary of the resources used by the terminated
|
|
process and all its
|
|
children is returned (this information is currently not available
|
|
for stopped processes).
|
|
.Pp
|
|
When the
|
|
.Dv WNOHANG
|
|
option is specified and no processes
|
|
wish to report status,
|
|
.Fn wait4
|
|
returns a
|
|
process id
|
|
of 0.
|
|
.Pp
|
|
The
|
|
.Fn waitpid
|
|
call is identical to
|
|
.Fn wait4
|
|
with an
|
|
.Fa rusage
|
|
value of zero.
|
|
The older
|
|
.Fn wait3
|
|
call is the same as
|
|
.Fn wait4
|
|
with a
|
|
.Fa wpid
|
|
value of \-1.
|
|
.Pp
|
|
The following macros may be used to test the manner of exit of the process.
|
|
Note that these macros expect the
|
|
.Fa status
|
|
value itself, not a pointer to the
|
|
.Fa status
|
|
value.
|
|
One of the first three macros will evaluate to a non-zero (true) value:
|
|
.Bl -tag -width Ds
|
|
.It Fn WIFEXITED status
|
|
True if the process terminated normally by a call to
|
|
.Xr _exit 2
|
|
or
|
|
.Xr exit 3 .
|
|
.It Fn WIFSIGNALED status
|
|
True if the process terminated due to receipt of a signal.
|
|
.It Fn WIFSTOPPED status
|
|
True if the process has not terminated, but has stopped and can be restarted.
|
|
This macro can be true only if the wait call specified the
|
|
.Dv WUNTRACED
|
|
option
|
|
or if the child process is being traced (see
|
|
.Xr ptrace 2 ) .
|
|
.El
|
|
.Pp
|
|
Depending on the values of those macros, the following macros
|
|
produce the remaining status information about the child process:
|
|
.Bl -tag -width Ds
|
|
.It Fn WEXITSTATUS status
|
|
If
|
|
.Fn WIFEXITED status
|
|
is true, evaluates to the low-order 8 bits
|
|
of the argument passed to
|
|
.Xr _exit 2
|
|
or
|
|
.Xr exit 3
|
|
by the child.
|
|
.It Fn WTERMSIG status
|
|
If
|
|
.Fn WIFSIGNALED status
|
|
is true, evaluates to the number of the signal
|
|
that caused the termination of the process.
|
|
.It Fn WCOREDUMP status
|
|
If
|
|
.Fn WIFSIGNALED status
|
|
is true, evaluates as true if the termination
|
|
of the process was accompanied by the creation of a core file
|
|
containing an image of the process when the signal was received.
|
|
.It Fn WSTOPSIG status
|
|
If
|
|
.Fn WIFSTOPPED status
|
|
is true, evaluates to the number of the signal
|
|
that caused the process to stop.
|
|
.El
|
|
.Sh NOTES
|
|
See
|
|
.Xr sigaction 2
|
|
for a list of termination signals.
|
|
A status of 0 indicates normal termination.
|
|
.Pp
|
|
If a parent process terminates without
|
|
waiting for all of its child processes to terminate,
|
|
the remaining child processes are assigned the parent
|
|
process 1 ID (the init process ID).
|
|
.Pp
|
|
If a signal is caught while any of the
|
|
.Fn wait
|
|
calls is pending,
|
|
the call may be interrupted or restarted when the signal-catching routine
|
|
returns,
|
|
depending on the options in effect for the signal;
|
|
see
|
|
.Xr intro 2 ,
|
|
System call restart.
|
|
.Sh RETURN VALUES
|
|
If
|
|
.Fn wait
|
|
returns due to a stopped
|
|
or terminated child process, the process ID of the child
|
|
is returned to the calling process.
|
|
Otherwise, a value of \-1 is returned and
|
|
.Va errno
|
|
is set to indicate the error.
|
|
.Pp
|
|
If
|
|
.Fn wait4 ,
|
|
.Fn wait3
|
|
or
|
|
.Fn waitpid
|
|
returns due to a stopped
|
|
or terminated child process, the process ID of the child
|
|
is returned to the calling process.
|
|
If there are no children not previously awaited,
|
|
\-1 is returned with
|
|
.Va errno
|
|
set to
|
|
.Bq Er ECHILD .
|
|
Otherwise, if
|
|
.Dv WNOHANG
|
|
is specified and there are
|
|
no stopped or exited children, 0 is returned.
|
|
If an error is detected or a caught signal aborts the call,
|
|
a value of \-1 is returned and
|
|
.Va errno
|
|
is set to indicate the error.
|
|
.Sh ERRORS
|
|
.Fn wait
|
|
will fail and return immediately if:
|
|
.Bl -tag -width Er
|
|
.It Bq Er ECHILD
|
|
The calling process has no existing unwaited-for child processes.
|
|
.It Bq Er EFAULT
|
|
The
|
|
.Fa status
|
|
or
|
|
.Fa rusage
|
|
arguments point to an illegal address.
|
|
(May not be detected before exit of a child process.)
|
|
.It Bq Er EINTR
|
|
The call was interrupted by a caught signal,
|
|
or the signal did not have the
|
|
.Dv SA_RESTART
|
|
flag set.
|
|
.El
|
|
.Pp
|
|
In addition,
|
|
.Fn wait3 ,
|
|
.Fn wait4 ,
|
|
and
|
|
.Fn waitpid
|
|
will fail and return immediately if:
|
|
.Bl -tag -width Er
|
|
.It Bq Er EINVAL
|
|
An invalid value was specified for
|
|
.Fa options .
|
|
.El
|
|
.Sh SEE ALSO
|
|
.Xr _exit 2 ,
|
|
.Xr sigaction 2
|
|
.Sh STANDARDS
|
|
The
|
|
.Fn wait
|
|
and
|
|
.Fn waitpid
|
|
functions conform to
|
|
.St -p1003.1-90 ;
|
|
the
|
|
.Fn wait3
|
|
function conforms to
|
|
.St -xpg4 ;
|
|
.Fn wait4
|
|
is an extension.
|
|
The
|
|
.Fn WCOREDUMP
|
|
macro
|
|
and the ability to restart a pending
|
|
.Fn wait
|
|
call are extensions to the POSIX interface.
|
|
.Sh HISTORY
|
|
A
|
|
.Fn wait
|
|
function call appeared in
|
|
.At v2 .
|