notify.3 (6650B)
1 .TH NOTIFY 3 2 .SH NAME 3 notify, noted, atnotify, noteenable, notedisable, notifyon, notifyoff \- handle asynchronous process notification 4 .SH SYNOPSIS 5 .B #include <u.h> 6 .br 7 .B #include <libc.h> 8 .PP 9 .B 10 int notify(void (*f)(void*, char*)) 11 .PP 12 .B 13 int noted(int v) 14 .PP 15 .B 16 int atnotify(int (*f)(void*, char*), int in) 17 .PP 18 .B 19 int noteenable(char *msg) 20 .br 21 .B 22 int notedisable(char *msg) 23 .PP 24 .B 25 int notifyon(char *msg) 26 .br 27 .B 28 int notifyoff(char *msg) 29 .SH DESCRIPTION 30 When a process raises an exceptional condition such as dividing by zero 31 or writing on a closed pipe, a 32 .I note 33 is posted to communicate the exception. 34 A note may also be posted by another process 35 via 36 .MR postnote (3) . 37 On Unix, notes are implemented as signals. 38 .PP 39 When a note is received, the action taken depends on the note. 40 See 41 .MR signal (7) 42 for the full description of the defaults. 43 .PP 44 The default actions may be overridden. 45 The 46 .I notify 47 function registers a 48 .I "notification handler 49 to be called within the process when a note is received. 50 The argument to 51 .I notify 52 replaces the previous handler, if any. 53 An argument of zero cancels a previous handler, 54 restoring the default action. 55 A 56 .MR fork (2) 57 system call leaves the handler registered in 58 both the parent and the child; 59 .MR exec (3) 60 restores the default behavior. 61 Handlers may not perform floating point operations. 62 .PP 63 After a note is posted, 64 the handler is called with two arguments: 65 the first is unimplemented and should not be used 66 (on Plan 9 67 it is a 68 .B Ureg 69 structure 70 giving the current values of registers); 71 the second is a pointer to the note itself, 72 a null-terminated string. 73 .\" The 74 .\" .B Ureg 75 .\" argument is usually not needed; it is provided to help recover from traps such 76 .\" as floating point exceptions. 77 .\" Its use and layout are machine- and system-specific. 78 .PP 79 A notification handler must finish either by exiting the program or by calling 80 .IR noted ; 81 if the handler returns the behavior 82 is undefined and probably erroneous. 83 Until the program calls 84 .IR noted , 85 any further externally-generated notes 86 (e.g., 87 .B hangup 88 or 89 .BR alarm ) 90 will be held off, and any further notes generated by 91 erroneous behavior by the program 92 (such as divide by zero) will kill the program. 93 The argument to 94 .I noted 95 defines the action to take: 96 .B NDFLT 97 instructs the system to perform the default action 98 as if the handler had never been registered; 99 .B NCONT 100 instructs the system to resume the process 101 at the point it was notified. 102 In neither case does 103 .I noted 104 return to the handler. 105 If the note interrupted an incomplete system call, 106 that call returns an error (with error string 107 .BR interrupted ) 108 after the process resumes. 109 A notification handler can also jump out to an environment 110 set up with 111 .I setjmp 112 using the 113 .I notejmp 114 function (see 115 .MR setjmp (3) ). 116 .PP 117 Unix provides a fixed set of notes (typically there are 32) called 118 .IR signals . 119 It also allows a process to block certain notes from being delivered 120 (see 121 .MR sigprocmask (2) ) 122 and to ignore certain notes by setting the signal hander to the special value 123 .B SIG_IGN 124 (see 125 .MR signal (2) ). 126 .I Noteenable 127 and 128 .I notedisable 129 enable or disable receipt of a particular note by changing the current process's blocked signal mask. 130 Receipt of a disabled note will be postponed until it is reenabled. 131 .I Notifyon 132 and 133 .I notifyoff 134 enable or disable whether the notification handler 135 is called upon receipt of the note; if the handler is not called, the note is discarded. 136 .PP 137 Regardless of the origin of the note or the presence of a handler, 138 if the process is being debugged 139 (see 140 .MR ptrace (2) ) 141 the arrival of a note puts the process in the 142 .B Stopped 143 state and awakens the debugger. 144 .PP 145 Rather than using the system calls 146 .I notify 147 and 148 .IR noted , 149 most programs should use 150 .I atnotify 151 to register notification handlers. 152 The parameter 153 .I in 154 is non-zero to register the function 155 .IR f , 156 and zero to cancel registration. 157 A handler must return a non-zero number 158 if the note was recognized (and resolved); 159 otherwise it must return zero. 160 When the system posts a note to the process, 161 each handler registered with 162 .I atnotify 163 is called with arguments as 164 described above 165 until one of the handlers returns non-zero. 166 Then 167 .I noted 168 is called with argument 169 .BR NCONT . 170 If no registered function returns non-zero, 171 .I atnotify 172 calls 173 .I noted 174 with argument 175 .BR NDFLT . 176 .\" .PP 177 .\" .I Noted 178 .\" has two other possible values for its argument. 179 .\" .B NSAVE 180 .\" returns from the handler and clears the note, enabling the receipt of another, 181 .\" but does not return to the program. 182 .\" Instead it starts a new handler with the same stack, stack pointer, 183 .\" and arguments as the 184 .\" original, at the address recorded in the program counter of the 185 .\" .B Ureg 186 .\" structure. Typically, the program counter will be overridden by the 187 .\" first note handler to be the address of a separate function; 188 .\" .B NSAVE 189 .\" is then a `trampoline' to that handler. 190 .\" That handler may executed 191 .\" .B noted(NRSTR) 192 .\" to return to the original program, usually after restoring the original program 193 .\" counter. 194 .\" .B NRSTR 195 .\" is identical to 196 .\" .BR NCONT 197 .\" except that it can only be executed after an 198 .\" .BR NSAVE . 199 .\" .B NSAVE 200 .\" and 201 .\" .B NRSTR 202 .\" are designed to improve the emulation of signals by the ANSI C/POSIX 203 .\" environment; their use elsewhere is discouraged. 204 .PP 205 .I Notify 206 and 207 .I atnotify 208 return \-1 on error and 0 on success. 209 .I Noted 210 returns \-1 on error; successful calls to 211 .I noted 212 do not return. 213 .I Noteenable 214 and 215 .I notedisable 216 .RI ( notitfyon 217 and 218 .IR notifyoff ) 219 return \-1 on error, 0 if the note was previously disabled (not notified), 220 and 1 if the note was previously enabled (notified). 221 .PP 222 The set of notes a process may receive is system-dependent, but there 223 is a common set that includes: 224 .PP 225 .RS 3n 226 .nf 227 .ta \w'\fLsys: segmentation violation \fP'u +\w'process requested to exit 'u 228 \fINote\fP \fIMeaning\fP \fIUnix signal\fP 229 \fLinterrupt\fP user interrupt (DEL key) SIGINTR 230 \fLhangup\fP I/O connection closed SIGHUP 231 \fLalarm\fP alarm expired SIGLARM 232 \fLquit\fP quit from keyboard SIGQUIT 233 \fLkill\fP process requested to exit SIGTERM 234 \fLsys: kill\fP process forced to exit SIGKILL 235 \fLsys: bus error\fP bus error SIGBUS 236 \fLsys: segmentation violation\fP segmentation violation SIGSEGV 237 \fLsys: write on closed pipe\fP write on closed pipe SIGPIPE 238 \fLsys: child\fP child wait status change SIGCHLD 239 .fi 240 .RE 241 .PP 242 See 243 .B \*9/src/lib9/await.c 244 (sic) 245 for the full list. 246 .PP 247 The notes prefixed 248 .B sys: 249 are usually generated by the operating system. 250 .SH SOURCE 251 .B \*9/src/lib9/notify.c 252 .br 253 .B \*9/src/lib9/atnotify.c 254 .SH SEE ALSO 255 .MR intro (3) , 256 .I notejmp 257 in 258 .MR setjmp (3)