123 lines
2.5 KiB
Plaintext
123 lines
2.5 KiB
Plaintext
.TH WAIT 2
|
|
.SH NAME
|
|
await, wait, waitpid \- wait for a process to exit
|
|
.SH SYNOPSIS
|
|
.B #include <u.h>
|
|
.br
|
|
.B #include <libc.h>
|
|
.PP
|
|
.B
|
|
Waitmsg* wait(void)
|
|
.PP
|
|
.B
|
|
int waitpid(void)
|
|
.PP
|
|
.B
|
|
int await(char *s, int n)
|
|
.SH DESCRIPTION
|
|
.I Wait
|
|
causes a process to wait for any child process (see
|
|
.IR fork (2))
|
|
to exit.
|
|
It returns a
|
|
.B Waitmsg
|
|
holding
|
|
information about the exited child.
|
|
A
|
|
.B Waitmsg
|
|
has this structure:
|
|
.IP
|
|
.EX
|
|
.ta 6n +\w'long 'u +\w'msg[ERRLEN]; 'u
|
|
typedef
|
|
struct Waitmsg
|
|
{
|
|
int pid; /* of loved one */
|
|
ulong time[3]; /* of loved one & descendants */
|
|
char *msg;
|
|
} Waitmsg;
|
|
.EE
|
|
.PP
|
|
.B Pid
|
|
is the child's
|
|
process id.
|
|
The
|
|
.B time
|
|
array contains the time the child and its descendants spent in user code,
|
|
the time spent in system calls, and the child's elapsed real time,
|
|
all in units of milliseconds.
|
|
.B Msg
|
|
contains the message that the child specified in
|
|
.IR exits (2).
|
|
For a normal exit,
|
|
.B msg[0]
|
|
is zero,
|
|
otherwise
|
|
.B msg
|
|
is the exit string
|
|
prefixed by the process name, a blank, the process id, and a colon.
|
|
.PP
|
|
If there are no more children to wait for,
|
|
.I wait
|
|
returns immediately, with return value nil.
|
|
.PP
|
|
The
|
|
.B Waitmsg
|
|
structure is allocated by
|
|
.IR malloc (2)
|
|
and should be freed after use.
|
|
For programs that only need the pid of the exiting program,
|
|
.I waitpid
|
|
returns just the pid and discards the rest of the information.
|
|
.PP
|
|
The underlying system call is
|
|
.IR await ,
|
|
which fills in the n-byte buffer
|
|
.I s
|
|
with a textual representation of the pid, times, and exit string.
|
|
There is no terminal NUL.
|
|
The return value is the length, in bytes, of the data.
|
|
.PP
|
|
The buffer filled in by
|
|
.I await
|
|
may be parsed (after appending a NUL) using
|
|
.IR tokenize
|
|
(see
|
|
.IR getfields (2));
|
|
the resulting fields are, in order, pid, the three times, and the exit string,
|
|
which will be
|
|
.B ''
|
|
for normal exit.
|
|
If the representation is longer than
|
|
.I n
|
|
bytes, it is truncated but, if possible, properly formatted.
|
|
The information that does not fit in the buffer is discarded, so
|
|
a subsequent call to
|
|
.I await
|
|
will return the information about the next exiting child, not the remainder
|
|
of the truncated message.
|
|
In other words, each call to
|
|
.I await
|
|
returns the information about one child, blocking if necessary if no child has exited.
|
|
.PP
|
|
If the calling process has no living children,
|
|
.I await
|
|
and
|
|
.I waitpid
|
|
return
|
|
.BR -1 .
|
|
.SH SOURCE
|
|
.B /sys/src/libc/9syscall
|
|
.br
|
|
.B /sys/src/libc/9sys
|
|
.SH "SEE ALSO"
|
|
.IR fork (2),
|
|
.IR exits (2),
|
|
the
|
|
.B wait
|
|
file in
|
|
.IR proc (3)
|
|
.SH DIAGNOSTICS
|
|
These routines set
|
|
.IR errstr .
|