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