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