WAIT(2)                                                   WAIT(2)

     NAME
          await, wait, waitpid - wait for a process to exit

     SYNOPSIS
          #include <u.h>
          #include <libc.h>

          Waitmsg*  wait(void)

          int       waitpid(void)

          int       await(char *s, int n)

     DESCRIPTION
          Wait causes a process to wait for any child process (see
          fork(2)) to exit.  It returns a Waitmsg holding information
          about the exited child.  A Waitmsg has this structure:

               typedef
               struct Waitmsg
               {
                     int pid;              /* of loved one */
                     ulong time[3];        /* of loved one & descendants */
                     char *msg;
               } Waitmsg;

          Pid is the child's process id.  The 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.  Msg contains the mes-
          sage that the child specified in exits(2). For a normal
          exit, msg[0] is zero, otherwise msg is the exit string pre-
          fixed by the process name, a blank, the process id, and a
          colon.

          If there are no more children to wait for, wait returns
          immediately, with return value nil.

          The Waitmsg structure is allocated by malloc(2) and should
          be freed after use.  For programs that only need the pid of
          the exiting program, waitpid returns just the pid and dis-
          cards the rest of the information.

          The underlying system call is await, which fills in the n-
          byte buffer 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.

          The buffer filled in by await may be parsed (after appending
          a NUL) using tokenize (see getfields(2)); the resulting

     WAIT(2)                                                   WAIT(2)

          fields are, in order, pid, the three times, and the exit
          string, which will be '' for normal exit.  If the represen-
          tation is longer than n bytes, it is truncated but, if pos-
          sible, properly formatted.  The information that does not
          fit in the buffer is discarded, so a subsequent call to
          await will return the information about the next exiting
          child, not the remainder of the truncated message.  In other
          words, each call to await returns the information about one
          child, blocking if necessary if no child has exited.

          If the calling process has no living children, await and
          waitpid return -1.

     SOURCE
          /sys/src/libc/9syscall
          /sys/src/libc/9sys

     SEE ALSO
          fork(2), exits(2), the wait file in proc(3)

     DIAGNOSTICS
          These routines set errstr.