1 .TH WAIT 3
2 .SH NAME
3 await, wait, 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 int 		waitpid(void)
14 .PP
15 .B
16 int 		await(char *s, int n)
17 .SH DESCRIPTION
18 .I Wait
19 causes a process to wait for any child process (see
20 .IR fork (3))
21 to exit.
22 It returns a
23 .B Waitmsg
24 holding
25 information about the exited child.
26 A
27 .B Waitmsg
28 has this structure:
29 .IP
30 .EX
31 .ta 6n +\w'long 'u +\w'msg[ERRLEN];     'u
32 typedef
33 struct Waitmsg
34 {
35 	int pid;	/* of loved one */
36 	ulong time[3];	/* of loved one & descendants */
37 	char	*msg;
38 } Waitmsg;
39 .EE
40 .PP
41 .B Pid
42 is the child's
43 process id.
44 The
45 .B time
46 array contains the time the child and its descendants spent in user code,
47 the time spent in system calls, and the child's elapsed real time,
48 all in units of milliseconds.
49 .B Msg
50 contains the message that the child specified in
51 .IR exits (3).
52 For a normal exit,
53 .B msg[0]
54 is zero,
55 otherwise
56 .B msg
57 is the exit string
58 prefixed by the process name, a blank, the process id, and a colon.
59 .PP
60 If there are no more children to wait for,
61 .I wait
62 returns immediately, with return value nil.
63 .PP
64 The
65 .B Waitmsg
66 structure is allocated by
67 .IR malloc (3)
68 and should be freed after use.
69 For programs that only need the pid of the exiting program,
70 .I waitpid
71 returns just the pid and discards the rest of the information.
72 .PP
73 The underlying system call is
74 .IR await ,
75 which fills in the n-byte buffer
76 .I s
77 with a textual representation of the pid, times, and exit string.
78 There is no terminal NUL.
79 The return value is the length, in bytes, of the data.
80 .PP
81 The buffer filled in by
82 .I await
83 may be parsed (after appending a NUL) using
84 .IR tokenize
85 (see
86 .IR getfields (3));
87 the resulting fields are, in order, pid, the three times, and the exit string,
88 which will be
89 .B ''
90 for normal exit.
91 If the representation is longer than
92 .I n
93 bytes, it is truncated but, if possible, properly formatted.
94 The information that does not fit in the buffer is discarded, so
95 a subsequent call to
96 .I await
97 will return the information about the next exiting child, not the remainder
98 of the truncated message.
99 In other words, each call to
100 .I await
101 returns the information about one child, blocking if necessary if no child has exited.
102 If the calling process has no living children,
103 .I await
104 returns
105 .BR -1 .
106 .SH SOURCE
107 .B /sys/src/libc/9syscall
108 .SH "SEE ALSO"
109 .IR fork (3),
110 .IR exits (3),
111 the
112 .B wait
113 file in
114 .IR proc (3)
115 .SH DIAGNOSTICS
116 These routines set
117 .IR errstr .