10564b1175
groff 1.23.0 added .MR to its -man macro package. The NEWS file states
that the inclusion of the macro "was prompted by its introduction to
Plan 9 from User Space's troff in August 2020." From d32deab it seems
that the name for Plan 9 from User Space's implementation was suggested
by groff maintainer G. Brandon Robinson.
Not sure if the intention was to make these definitions compatible, but
it would be nice if they were.
Currently, Plan 9 from User Space's .MR expects its second argument to
be parenthesized. groff's .MR does not. This results in extra
parentheses appearing in manual references when viewing Plan 9 from User
Space's manual pages on a system using groff.
160 lines
3.1 KiB
Groff
160 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 .
|