| rsc | cfa37a7 | 2004-04-10 18:53:55 +0000 | [diff] [blame^] | 1 | .TH WAIT 3 |
| 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 | If the calling process has no living children, |
| 103 | .I await |
| 104 | returns |
| 105 | .BR -1 . |
| 106 | .SH SOURCE |
| 107 | .B /sys/src/libc/9syscall |
| 108 | .SH "SEE ALSO" |
| 109 | .IR fork (2), |
| 110 | .IR exits (2), |
| 111 | the |
| 112 | .B wait |
| 113 | file in |
| 114 | .IR proc (3) |
| 115 | .SH DIAGNOSTICS |
| 116 | These routines set |
| 117 | .IR errstr . |
