WAIT(3)                                                   WAIT(3)

     NAME
          await, awaitnohang, awaitfor, wait, waitnohang, waitfor,
          waitpid - wait for a process to exit

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

          Waitmsg*  wait(void)

          Waitmsg*  waitnohang(void)

          Waitmsg*  waitfor(int pid)

          int       waitpid(void)

          int       await(char *s, int n)

          int       awaitnohang(char *s, int n)

          int       awaitfor(int pid, char *s, int n)

     DESCRIPTION
          Wait causes a process to wait for any child process (see
          fork(2) and rfork(3)) 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(3). 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(3) and should
          be freed after use.  For programs that only need the pid of

     WAIT(3)                                                   WAIT(3)

          the exiting program, waitpid returns just the pid and dis-
          cards the rest of the information.

          Waitnohang is like wait but does not block if there are no
          more children to wait for.  Instead it returns immediately
          and sets errstr.

          Waitfor is like wait but waits for a particular pid.

          The underlying calls are await, awaitnohang, and awaitfor,
          which fill in the n-byte buffer s with a textual representa-
          tion of the pid, times, and exit string.  There is no termi-
          nal NUL.  The return value is the length, in bytes, of the
          data.

          The filled-in buffer may be parsed (after appending a NUL)
          using tokenize (see getfields(3)); the resulting fields are,
          in order, pid, the three times, and the exit string, which
          will be '' for normal exit.  If the representation is longer
          than 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 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 returns -1.

     SOURCE
          /src/lib9/wait.c

          /src/lib9/await.c

     SEE ALSO
          rfork(3), exits(3),

     DIAGNOSTICS
          These routines set errstr.

     BUGS
          To avoid name conflicts with the underlying system, wait,
          waitpid, and waitfor are preprocessor macros defined as
          p9wait, p9waitpid, and p9waitfor; see intro(3).