sys/man/2/wait

   1 .TH WAIT 2
   2 .SH NAME
   3 await, wait, waitpid \- wait for a process to exit
   4 .SH SYNOPSIS
   5 .B #include <u.h>
   6 .br
   7 .B #include <libc.h>
   8 .PP
   9 .B
  10 Waitmsg*        wait(void)
  11 .PP
  12 .B
  13 int             waitpid(void)
  14 .PP
  15 .B
  16 int             await(char *s, int n)
  17 .SH DESCRIPTION
  18 .I Wait
  19 causes a process to wait for any child process (see
  20 .IR fork (2))
  21 to exit.
  22 It returns a
  23 .B Waitmsg
  24 holding
  25 information about the exited child.
  26 A
  27 .B Waitmsg
  28 has this structure:
  29 .IP
  30 .EX
  31 .ta 6n +\w'long 'u +\w'msg[ERRLEN];     'u
  32 typedef
  33 struct Waitmsg
  34 {
  35         int pid;        /* of loved one */
  36         ulong time[3];  /* of loved one & descendants */
  37         char    *msg;
  38 } Waitmsg;
  39 .EE
  40 .PP
  41 .B Pid
  42 is the child's
  43 process id.
  44 The
  45 .B time
  46 array contains the time the child and its descendants spent in user code,
  47 the time spent in system calls, and the child's elapsed real time,
  48 all in units of milliseconds.
  49 .B Msg
  50 contains the message that the child specified in
  51 .IR exits (2).
  52 For a normal exit,
  53 .B msg[0]
  54 is zero,
  55 otherwise
  56 .B msg
  57 is the exit string
  58 prefixed by the process name, a blank, the process id, and a colon.
  59 .PP
  60 If there are no more children to wait for,
  61 .I wait
  62 returns immediately, with return value nil.
  63 .PP
  64 The
  65 .B Waitmsg
  66 structure is allocated by
  67 .IR malloc (2)
  68 and should be freed after use.
  69 For programs that only need the pid of the exiting program,
  70 .I waitpid
  71 returns just the pid and discards the rest of the information.
  72 .PP
  73 The underlying system call is
  74 .IR await ,
  75 which fills in the n-byte buffer
  76 .I s
  77 with a textual representation of the pid, times, and exit string.
  78 There is no terminal NUL.
  79 The return value is the length, in bytes, of the data.
  80 .PP
  81 The buffer filled in by
  82 .I await
  83 may be parsed (after appending a NUL) using
  84 .IR tokenize
  85 (see
  86 .IR getfields (2));
  87 the resulting fields are, in order, pid, the three times, and the exit string,
  88 which will be
  89 .B ''
  90 for normal exit.
  91 If the representation is longer than
  92 .I n
  93 bytes, it is truncated but, if possible, properly formatted.
  94 The information that does not fit in the buffer is discarded, so
  95 a subsequent call to
  96 .I await
  97 will return the information about the next exiting child, not the remainder
  98 of the truncated message.
  99 In other words, each call to
 100 .I await
 101 returns the information about one child, blocking if necessary if no child has exited.
 102 .PP
 103 If the calling process has no living children,
 104 .I await
 105 and
 106 .I waitpid
 107 return
 108 .BR -1 .
 109 .SH SOURCE
 110 .B /sys/src/libc/9syscall
 111 .br
 112 .B /sys/src/libc/9sys
 113 .SH "SEE ALSO"
 114 .IR fork (2),
 115 .IR exits (2),
 116 the
 117 .B wait
 118 file in
 119 .IR proc (3)
 120 .SH DIAGNOSTICS
 121 These routines set
 122 .IR errstr .