1 files changed, 117 insertions, 0 deletions
diff --git a/man/man3/wait.3 b/man/man3/wait.3
new file mode 100644
index 00000000..d29fc719
--- /dev/null
+++ b/man/man3/wait.3
@@ -0,0 +1,117 @@
+.TH WAIT 3
+.SH NAME
+await, wait, 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
+int 		waitpid(void)
+.PP
+.B
+int 		await(char *s, int n)
+.SH DESCRIPTION
+.I Wait
+causes a process to wait for any child process (see
+.IR fork (2))
+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 (2).
+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 (2)
+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
+The underlying system call is
+.IR await ,
+which fills in the 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 buffer filled in by
+.I await
+may be parsed (after appending a NUL) using
+.IR tokenize
+(see
+.IR getfields (2));
+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 /sys/src/libc/9syscall
+.SH "SEE ALSO"
+.IR fork (2),
+.IR exits (2),
+the
+.B wait
+file in
+.IR proc (3)
+.SH DIAGNOSTICS
+These routines set
+.IR errstr .