1 .TH WAIT 3
2 .SH NAME
3 await, awaitnohang, awaitfor, wait, waitnohang, waitfor, waitpid \- wait for a process to exit
4 .SH SYNOPSIS
5 .B #include <u.h>
6 .br
7 .B #include <libc.h>
8 .PP
9 .B
10 Waitmsg*	wait(void)
11 .PP
12 .B
13 Waitmsg*	waitnohang(void)
14 .PP
15 .B
16 Waitmsg*	waitfor(int pid)
17 .PP
18 .B
19 int 		waitpid(void)
20 .PP
21 .B
22 int 		await(char *s, int n)
23 .PP
24 .B
25 int		awaitnohang(char *s, int n)
26 .PP
27 .B
28 int		awaitfor(int pid, char *s, int n)
29 .SH DESCRIPTION
30 .I Wait
31 causes a process to wait for any child process (see
32 .MR fork (2)
33 and
34 .MR rfork (3) )
35 to exit.
36 It returns a
37 .B Waitmsg
38 holding
39 information about the exited child.
40 A
41 .B Waitmsg
42 has this structure:
43 .IP
44 .EX
45 .ta 6n +\w'long 'u +\w'msg[ERRLEN];     'u
46 typedef
47 struct Waitmsg
48 {
49 	int pid;	/* of loved one */
50 	ulong time[3];	/* of loved one & descendants */
51 	char	*msg;
52 } Waitmsg;
53 .EE
54 .PP
55 .B Pid
56 is the child's
57 process id.
58 The
59 .B time
60 array contains the time the child and its descendants spent in user code,
61 the time spent in system calls, and the child's elapsed real time,
62 all in units of milliseconds.
63 .B Msg
64 contains the message that the child specified in
65 .MR exits (3) .
66 For a normal exit,
67 .B msg[0]
68 is zero,
69 otherwise
70 .B msg
71 is the exit string
72 prefixed by the process name, a blank, the process id, and a colon.
73 .PP
74 If there are no more children to wait for,
75 .I wait
76 returns immediately, with return value nil.
77 .PP
78 The
79 .B Waitmsg
80 structure is allocated by
81 .MR malloc (3)
82 and should be freed after use.
83 For programs that only need the pid of the exiting program,
84 .I waitpid
85 returns just the pid and discards the rest of the information.
86 .PP
87 .I Waitnohang
88 is like
89 .I wait
90 but does not block if there are no more children to wait for.
91 Instead it returns immediately and sets
92 .IR errstr .
93 .PP
94 .I Waitfor
95 is like
96 .I wait
97 but waits for a particular
98 .IR pid .
99 .PP
100 The underlying calls are
101 .IR await ,
102 .IR awaitnohang ,
103 and
104 .IR awaitfor ,
105 which fill in the 
106 .IR n -byte
107 buffer
108 .I s
109 with a textual representation of the pid, times, and exit string.
110 There is no terminal NUL.
111 The return value is the length, in bytes, of the data.
112 .PP
113 The filled-in buffer
114 may be parsed (after appending a NUL) using
115 .IR tokenize
116 (see
117 .MR getfields (3) );
118 the resulting fields are, in order, pid, the three times, and the exit string,
119 which will be
120 .B ''
121 for normal exit.
122 If the representation is longer than
123 .I n
124 bytes, it is truncated but, if possible, properly formatted.
125 The information that does not fit in the buffer is discarded, so
126 a subsequent call to
127 .I await
128 will return the information about the next exiting child, not the remainder
129 of the truncated message.
130 In other words, each call to
131 .I await
132 returns the information about one child, blocking if necessary if no child has exited.
133 If the calling process has no living children,
134 .I await
135 returns
136 .BR -1 .
137 .SH SOURCE
138 .B \*9/src/lib9/wait.c
139 .PP
140 .B \*9/src/lib9/await.c
141 .SH "SEE ALSO"
142 .MR rfork (3) ,
143 .MR exits (3) ,
144 .SH DIAGNOSTICS
145 These routines set
146 .IR errstr .
147 .SH BUGS
148 To avoid name conflicts with the underlying system,
149 .IR wait ,
150 .IR waitpid ,
151 and
152 .I waitfor
153 are preprocessor macros defined as
154 .IR p9wait ,
155 .IR p9waitpid ,
156 and
157 .IR p9waitfor ;
158 see 
159 .MR intro (3) .