1 cfa37a7b 2004-04-10 devnull .TH WAIT 3
3 058b0118 2005-01-03 devnull await, awaitnohang, awaitfor, wait, waitnohang, waitfor, waitpid \- wait for a process to exit
4 cfa37a7b 2004-04-10 devnull .SH SYNOPSIS
5 cfa37a7b 2004-04-10 devnull .B #include <u.h>
7 cfa37a7b 2004-04-10 devnull .B #include <libc.h>
10 cfa37a7b 2004-04-10 devnull Waitmsg* wait(void)
13 058b0118 2005-01-03 devnull Waitmsg* waitnohang(void)
16 058b0118 2005-01-03 devnull Waitmsg* waitfor(int pid)
19 cfa37a7b 2004-04-10 devnull int waitpid(void)
22 cfa37a7b 2004-04-10 devnull int await(char *s, int n)
25 058b0118 2005-01-03 devnull int awaitnohang(char *s, int n)
28 058b0118 2005-01-03 devnull int awaitfor(int pid, char *s, int n)
29 cfa37a7b 2004-04-10 devnull .SH DESCRIPTION
31 cfa37a7b 2004-04-10 devnull causes a process to wait for any child process (see
34 d32deab1 2020-08-16 rsc .MR rfork (3) )
36 cfa37a7b 2004-04-10 devnull It returns a
37 cfa37a7b 2004-04-10 devnull .B Waitmsg
39 cfa37a7b 2004-04-10 devnull information about the exited child.
41 cfa37a7b 2004-04-10 devnull .B Waitmsg
42 cfa37a7b 2004-04-10 devnull has this structure:
45 cfa37a7b 2004-04-10 devnull .ta 6n +\w'long 'u +\w'msg[ERRLEN]; 'u
47 cfa37a7b 2004-04-10 devnull struct Waitmsg
49 cfa37a7b 2004-04-10 devnull int pid; /* of loved one */
50 cfa37a7b 2004-04-10 devnull ulong time[3]; /* of loved one & descendants */
51 cfa37a7b 2004-04-10 devnull char *msg;
52 cfa37a7b 2004-04-10 devnull } Waitmsg;
56 cfa37a7b 2004-04-10 devnull is the child's
57 cfa37a7b 2004-04-10 devnull process id.
60 cfa37a7b 2004-04-10 devnull array contains the time the child and its descendants spent in user code,
61 cfa37a7b 2004-04-10 devnull the time spent in system calls, and the child's elapsed real time,
62 cfa37a7b 2004-04-10 devnull all in units of milliseconds.
64 cfa37a7b 2004-04-10 devnull contains the message that the child specified in
65 d32deab1 2020-08-16 rsc .MR exits (3) .
66 cfa37a7b 2004-04-10 devnull For a normal exit,
67 cfa37a7b 2004-04-10 devnull .B msg[0]
69 cfa37a7b 2004-04-10 devnull otherwise
71 cfa37a7b 2004-04-10 devnull is the exit string
72 cfa37a7b 2004-04-10 devnull prefixed by the process name, a blank, the process id, and a colon.
74 cfa37a7b 2004-04-10 devnull If there are no more children to wait for,
76 cfa37a7b 2004-04-10 devnull returns immediately, with return value nil.
79 cfa37a7b 2004-04-10 devnull .B Waitmsg
80 cfa37a7b 2004-04-10 devnull structure is allocated by
81 d32deab1 2020-08-16 rsc .MR malloc (3)
82 cfa37a7b 2004-04-10 devnull and should be freed after use.
83 cfa37a7b 2004-04-10 devnull For programs that only need the pid of the exiting program,
84 cfa37a7b 2004-04-10 devnull .I waitpid
85 cfa37a7b 2004-04-10 devnull returns just the pid and discards the rest of the information.
87 058b0118 2005-01-03 devnull .I Waitnohang
90 058b0118 2005-01-03 devnull but does not block if there are no more children to wait for.
91 058b0118 2005-01-03 devnull Instead it returns immediately and sets
92 058b0118 2005-01-03 devnull .IR errstr .
94 058b0118 2005-01-03 devnull .I Waitfor
97 058b0118 2005-01-03 devnull but waits for a particular
98 058b0118 2005-01-03 devnull .IR pid .
100 058b0118 2005-01-03 devnull The underlying calls are
101 cfa37a7b 2004-04-10 devnull .IR await ,
102 058b0118 2005-01-03 devnull .IR awaitnohang ,
104 058b0118 2005-01-03 devnull .IR awaitfor ,
105 058b0118 2005-01-03 devnull which fill in the
106 058b0118 2005-01-03 devnull .IR n -byte
109 cfa37a7b 2004-04-10 devnull with a textual representation of the pid, times, and exit string.
110 cfa37a7b 2004-04-10 devnull There is no terminal NUL.
111 cfa37a7b 2004-04-10 devnull The return value is the length, in bytes, of the data.
113 058b0118 2005-01-03 devnull The filled-in buffer
114 cfa37a7b 2004-04-10 devnull may be parsed (after appending a NUL) using
115 cfa37a7b 2004-04-10 devnull .IR tokenize
117 d32deab1 2020-08-16 rsc .MR getfields (3) );
118 cfa37a7b 2004-04-10 devnull the resulting fields are, in order, pid, the three times, and the exit string,
119 cfa37a7b 2004-04-10 devnull which will be
121 cfa37a7b 2004-04-10 devnull for normal exit.
122 cfa37a7b 2004-04-10 devnull If the representation is longer than
124 cfa37a7b 2004-04-10 devnull bytes, it is truncated but, if possible, properly formatted.
125 cfa37a7b 2004-04-10 devnull The information that does not fit in the buffer is discarded, so
126 cfa37a7b 2004-04-10 devnull a subsequent call to
127 cfa37a7b 2004-04-10 devnull .I await
128 cfa37a7b 2004-04-10 devnull will return the information about the next exiting child, not the remainder
129 cfa37a7b 2004-04-10 devnull of the truncated message.
130 cfa37a7b 2004-04-10 devnull In other words, each call to
131 cfa37a7b 2004-04-10 devnull .I await
132 cfa37a7b 2004-04-10 devnull returns the information about one child, blocking if necessary if no child has exited.
133 cfa37a7b 2004-04-10 devnull If the calling process has no living children,
134 cfa37a7b 2004-04-10 devnull .I await
136 cfa37a7b 2004-04-10 devnull .BR -1 .
137 cfa37a7b 2004-04-10 devnull .SH SOURCE
138 c3674de4 2005-01-11 devnull .B \*9/src/lib9/wait.c
140 c3674de4 2005-01-11 devnull .B \*9/src/lib9/await.c
141 cfa37a7b 2004-04-10 devnull .SH "SEE ALSO"
142 d32deab1 2020-08-16 rsc .MR rfork (3) ,
143 d32deab1 2020-08-16 rsc .MR exits (3) ,
144 cfa37a7b 2004-04-10 devnull .SH DIAGNOSTICS
145 cfa37a7b 2004-04-10 devnull These routines set
146 cfa37a7b 2004-04-10 devnull .IR errstr .
147 c8b6342d 2005-01-13 devnull .SH BUGS
148 c8b6342d 2005-01-13 devnull To avoid name conflicts with the underlying system,
149 c8b6342d 2005-01-13 devnull .IR wait ,
150 c8b6342d 2005-01-13 devnull .IR waitpid ,
152 c8b6342d 2005-01-13 devnull .I waitfor
153 c8b6342d 2005-01-13 devnull are preprocessor macros defined as
154 c8b6342d 2005-01-13 devnull .IR p9wait ,
155 c8b6342d 2005-01-13 devnull .IR p9waitpid ,
157 c8b6342d 2005-01-13 devnull .IR p9waitfor ;
159 d32deab1 2020-08-16 rsc .MR intro (3) .
