mirror of
https://github.com/9fans/plan9port.git
synced 2025-01-12 11:10:07 +00:00
159 lines
3.1 KiB
Groff
159 lines
3.1 KiB
Groff
.TH WAIT 3
|
|
.SH NAME
|
|
await, awaitnohang, awaitfor, wait, waitnohang, waitfor, 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
|
|
Waitmsg* waitnohang(void)
|
|
.PP
|
|
.B
|
|
Waitmsg* waitfor(int pid)
|
|
.PP
|
|
.B
|
|
int waitpid(void)
|
|
.PP
|
|
.B
|
|
int await(char *s, int n)
|
|
.PP
|
|
.B
|
|
int awaitnohang(char *s, int n)
|
|
.PP
|
|
.B
|
|
int awaitfor(int pid, char *s, int n)
|
|
.SH DESCRIPTION
|
|
.I Wait
|
|
causes a process to wait for any child process (see
|
|
.MR fork (2)
|
|
and
|
|
.MR rfork (3) )
|
|
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
|
|
.MR exits (3) .
|
|
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
|
|
.MR malloc (3)
|
|
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
|
|
.I Waitnohang
|
|
is like
|
|
.I wait
|
|
but does not block if there are no more children to wait for.
|
|
Instead it returns immediately and sets
|
|
.IR errstr .
|
|
.PP
|
|
.I Waitfor
|
|
is like
|
|
.I wait
|
|
but waits for a particular
|
|
.IR pid .
|
|
.PP
|
|
The underlying calls are
|
|
.IR await ,
|
|
.IR awaitnohang ,
|
|
and
|
|
.IR awaitfor ,
|
|
which fill in the
|
|
.IR 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 filled-in buffer
|
|
may be parsed (after appending a NUL) using
|
|
.IR tokenize
|
|
(see
|
|
.MR getfields (3) );
|
|
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.
|
|
If the calling process has no living children,
|
|
.I await
|
|
returns
|
|
.BR -1 .
|
|
.SH SOURCE
|
|
.B \*9/src/lib9/wait.c
|
|
.PP
|
|
.B \*9/src/lib9/await.c
|
|
.SH "SEE ALSO"
|
|
.MR rfork (3) ,
|
|
.MR exits (3) ,
|
|
.SH DIAGNOSTICS
|
|
These routines set
|
|
.IR errstr .
|
|
.SH BUGS
|
|
To avoid name conflicts with the underlying system,
|
|
.IR wait ,
|
|
.IR waitpid ,
|
|
and
|
|
.I waitfor
|
|
are preprocessor macros defined as
|
|
.IR p9wait ,
|
|
.IR p9waitpid ,
|
|
and
|
|
.IR p9waitfor ;
|
|
see
|
|
.MR intro (3) .
|