1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
|
.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
.IR fork (2)
and
.IR 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
.IR 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
.IR 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
.IR 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 /usr/local/plan9/src/lib9/wait.c
.PP
.B /usr/local/plan9/src/lib9/await.c
.SH "SEE ALSO"
.IR rfork (3),
.IR exits (3),
.SH DIAGNOSTICS
These routines set
.IR errstr .
|