wait.3 (3141B)
1 .TH WAIT 3 2 .SH NAME 3 await, awaitnohang, awaitfor, wait, waitnohang, waitfor, 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 Waitmsg* waitnohang(void) 14 .PP 15 .B 16 Waitmsg* waitfor(int pid) 17 .PP 18 .B 19 int waitpid(void) 20 .PP 21 .B 22 int await(char *s, int n) 23 .PP 24 .B 25 int awaitnohang(char *s, int n) 26 .PP 27 .B 28 int awaitfor(int pid, char *s, int n) 29 .SH DESCRIPTION 30 .I Wait 31 causes a process to wait for any child process (see 32 .MR fork (2) 33 and 34 .MR rfork (3) ) 35 to exit. 36 It returns a 37 .B Waitmsg 38 holding 39 information about the exited child. 40 A 41 .B Waitmsg 42 has this structure: 43 .IP 44 .EX 45 .ta 6n +\w'long 'u +\w'msg[ERRLEN]; 'u 46 typedef 47 struct Waitmsg 48 { 49 int pid; /* of loved one */ 50 ulong time[3]; /* of loved one & descendants */ 51 char *msg; 52 } Waitmsg; 53 .EE 54 .PP 55 .B Pid 56 is the child's 57 process id. 58 The 59 .B time 60 array contains the time the child and its descendants spent in user code, 61 the time spent in system calls, and the child's elapsed real time, 62 all in units of milliseconds. 63 .B Msg 64 contains the message that the child specified in 65 .MR exits (3) . 66 For a normal exit, 67 .B msg[0] 68 is zero, 69 otherwise 70 .B msg 71 is the exit string 72 prefixed by the process name, a blank, the process id, and a colon. 73 .PP 74 If there are no more children to wait for, 75 .I wait 76 returns immediately, with return value nil. 77 .PP 78 The 79 .B Waitmsg 80 structure is allocated by 81 .MR malloc (3) 82 and should be freed after use. 83 For programs that only need the pid of the exiting program, 84 .I waitpid 85 returns just the pid and discards the rest of the information. 86 .PP 87 .I Waitnohang 88 is like 89 .I wait 90 but does not block if there are no more children to wait for. 91 Instead it returns immediately and sets 92 .IR errstr . 93 .PP 94 .I Waitfor 95 is like 96 .I wait 97 but waits for a particular 98 .IR pid . 99 .PP 100 The underlying calls are 101 .IR await , 102 .IR awaitnohang , 103 and 104 .IR awaitfor , 105 which fill in the 106 .IR n -byte 107 buffer 108 .I s 109 with a textual representation of the pid, times, and exit string. 110 There is no terminal NUL. 111 The return value is the length, in bytes, of the data. 112 .PP 113 The filled-in buffer 114 may be parsed (after appending a NUL) using 115 .IR tokenize 116 (see 117 .MR getfields (3) ); 118 the resulting fields are, in order, pid, the three times, and the exit string, 119 which will be 120 .B '' 121 for normal exit. 122 If the representation is longer than 123 .I n 124 bytes, it is truncated but, if possible, properly formatted. 125 The information that does not fit in the buffer is discarded, so 126 a subsequent call to 127 .I await 128 will return the information about the next exiting child, not the remainder 129 of the truncated message. 130 In other words, each call to 131 .I await 132 returns the information about one child, blocking if necessary if no child has exited. 133 If the calling process has no living children, 134 .I await 135 returns 136 .BR -1 . 137 .SH SOURCE 138 .B \*9/src/lib9/wait.c 139 .PP 140 .B \*9/src/lib9/await.c 141 .SH "SEE ALSO" 142 .MR rfork (3) , 143 .MR exits (3) , 144 .SH DIAGNOSTICS 145 These routines set 146 .IR errstr . 147 .SH BUGS 148 To avoid name conflicts with the underlying system, 149 .IR wait , 150 .IR waitpid , 151 and 152 .I waitfor 153 are preprocessor macros defined as 154 .IR p9wait , 155 .IR p9waitpid , 156 and 157 .IR p9waitfor ; 158 see 159 .MR intro (3) .