1 cfa37a7b 2004-04-10 devnull .TH NOTIFY 3
3 cfa37a7b 2004-04-10 devnull notify, noted, atnotify \- 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)
17 cfa37a7b 2004-04-10 devnull .SH DESCRIPTION
18 cfa37a7b 2004-04-10 devnull When a process raises an exceptional condition such as dividing by zero
19 cfa37a7b 2004-04-10 devnull or writing on a closed pipe, a
21 cfa37a7b 2004-04-10 devnull is posted to communicate the exception.
22 cfa37a7b 2004-04-10 devnull A note may also be posted by a
25 bf8a59fa 2004-04-11 devnull .IR read (3))
26 cfa37a7b 2004-04-10 devnull to the process's
27 cfa37a7b 2004-04-10 devnull .BI /proc/ n /note
28 cfa37a7b 2004-04-10 devnull file or to the
29 cfa37a7b 2004-04-10 devnull .BI /proc/ m /notepg
30 cfa37a7b 2004-04-10 devnull file of a process in the same process group (see
31 cfa37a7b 2004-04-10 devnull .IR proc (3)).
32 cfa37a7b 2004-04-10 devnull When the note is received
33 cfa37a7b 2004-04-10 devnull the behavior of the process depends on the origin of the note.
34 cfa37a7b 2004-04-10 devnull If the note was posted by an external process,
35 cfa37a7b 2004-04-10 devnull the process receiving the note exits;
36 cfa37a7b 2004-04-10 devnull if generated by the system the note string,
37 cfa37a7b 2004-04-10 devnull preceded by the name
38 cfa37a7b 2004-04-10 devnull and id of the process and the string
39 cfa37a7b 2004-04-10 devnull \fL"suicide: "\fP,
40 cfa37a7b 2004-04-10 devnull is printed on the process's standard error file
42 cfa37a7b 2004-04-10 devnull process is suspended in the
43 cfa37a7b 2004-04-10 devnull .B Broken
44 cfa37a7b 2004-04-10 devnull state for debugging.
46 cfa37a7b 2004-04-10 devnull These default actions may be overridden.
48 cfa37a7b 2004-04-10 devnull .I notify
49 cfa37a7b 2004-04-10 devnull function registers a
50 cfa37a7b 2004-04-10 devnull .I "notification handler
51 cfa37a7b 2004-04-10 devnull to be called within the process when a note is received.
52 cfa37a7b 2004-04-10 devnull The argument to
53 cfa37a7b 2004-04-10 devnull .I notify
54 cfa37a7b 2004-04-10 devnull replaces the previous handler, if any.
55 cfa37a7b 2004-04-10 devnull An argument of zero cancels a previous handler,
56 cfa37a7b 2004-04-10 devnull restoring the default action.
58 bf8a59fa 2004-04-11 devnull .IR fork (3)
59 cfa37a7b 2004-04-10 devnull system call leaves the handler registered in
60 cfa37a7b 2004-04-10 devnull both the parent and the child;
61 bf8a59fa 2004-04-11 devnull .IR exec (3)
62 cfa37a7b 2004-04-10 devnull restores the default behavior.
63 cfa37a7b 2004-04-10 devnull Handlers may not perform floating point operations.
65 cfa37a7b 2004-04-10 devnull After a note is posted,
66 cfa37a7b 2004-04-10 devnull the handler is called with two arguments:
67 cfa37a7b 2004-04-10 devnull the first is a pointer to a
69 cfa37a7b 2004-04-10 devnull structure (defined in
70 cfa37a7b 2004-04-10 devnull .BR /$objtype/include/ureg.h )
71 cfa37a7b 2004-04-10 devnull giving the current values of registers;
72 cfa37a7b 2004-04-10 devnull the second is a pointer to the note itself,
73 cfa37a7b 2004-04-10 devnull a null-terminated string with no more than
74 cfa37a7b 2004-04-10 devnull .L ERRLEN
75 cfa37a7b 2004-04-10 devnull characters in it including the terminal NUL.
78 cfa37a7b 2004-04-10 devnull argument is usually not needed; it is provided to help recover from traps such
79 cfa37a7b 2004-04-10 devnull as floating point exceptions.
80 cfa37a7b 2004-04-10 devnull Its use and layout are machine- and system-specific.
82 cfa37a7b 2004-04-10 devnull A notification handler must finish either by exiting the program or by calling
83 cfa37a7b 2004-04-10 devnull .IR noted ;
84 cfa37a7b 2004-04-10 devnull if the handler returns the behavior
85 cfa37a7b 2004-04-10 devnull is undefined and probably erroneous.
86 cfa37a7b 2004-04-10 devnull Until the program calls
87 cfa37a7b 2004-04-10 devnull .IR noted ,
88 cfa37a7b 2004-04-10 devnull any further externally-generated notes
90 cfa37a7b 2004-04-10 devnull .B hangup
92 cfa37a7b 2004-04-10 devnull .BR alarm )
93 cfa37a7b 2004-04-10 devnull will be held off, and any further notes generated by
94 cfa37a7b 2004-04-10 devnull erroneous behavior by the program
95 cfa37a7b 2004-04-10 devnull (such as divide by zero) will kill the program.
96 cfa37a7b 2004-04-10 devnull The argument to
98 cfa37a7b 2004-04-10 devnull defines the action to take:
100 cfa37a7b 2004-04-10 devnull instructs the system to perform the default action
101 cfa37a7b 2004-04-10 devnull as if the handler had never been registered;
102 cfa37a7b 2004-04-10 devnull .B NCONT
103 cfa37a7b 2004-04-10 devnull instructs the system to resume the process
104 cfa37a7b 2004-04-10 devnull at the point it was notified.
105 cfa37a7b 2004-04-10 devnull In neither case does
106 cfa37a7b 2004-04-10 devnull .I noted
107 cfa37a7b 2004-04-10 devnull return to the handler.
108 cfa37a7b 2004-04-10 devnull If the note interrupted an incomplete system call,
109 cfa37a7b 2004-04-10 devnull that call returns an error (with error string
110 cfa37a7b 2004-04-10 devnull .BR interrupted )
111 cfa37a7b 2004-04-10 devnull after the process resumes.
112 cfa37a7b 2004-04-10 devnull A notification handler can also jump out to an environment
113 cfa37a7b 2004-04-10 devnull set up with
114 cfa37a7b 2004-04-10 devnull .I setjmp
115 cfa37a7b 2004-04-10 devnull using the
116 cfa37a7b 2004-04-10 devnull .I notejmp
117 cfa37a7b 2004-04-10 devnull function (see
118 bf8a59fa 2004-04-11 devnull .IR setjmp (3)),
119 cfa37a7b 2004-04-10 devnull which is implemented by modifying the saved state and calling
120 cfa37a7b 2004-04-10 devnull .BR noted(NCONT) .
122 cfa37a7b 2004-04-10 devnull Regardless of the origin of the note or the presence of a handler,
123 cfa37a7b 2004-04-10 devnull if the process is being debugged
125 cfa37a7b 2004-04-10 devnull .IR proc (3))
126 cfa37a7b 2004-04-10 devnull the arrival of a note puts the process in the
127 cfa37a7b 2004-04-10 devnull .B Stopped
128 cfa37a7b 2004-04-10 devnull state and awakens the debugger.
130 cfa37a7b 2004-04-10 devnull Rather than using the system calls
131 cfa37a7b 2004-04-10 devnull .I notify
133 cfa37a7b 2004-04-10 devnull .IR noted ,
134 cfa37a7b 2004-04-10 devnull most programs should use
135 cfa37a7b 2004-04-10 devnull .I atnotify
136 cfa37a7b 2004-04-10 devnull to register notification handlers.
137 cfa37a7b 2004-04-10 devnull The parameter
139 cfa37a7b 2004-04-10 devnull is non-zero to register the function
141 cfa37a7b 2004-04-10 devnull and zero to cancel registration.
142 cfa37a7b 2004-04-10 devnull A handler must return a non-zero number
143 cfa37a7b 2004-04-10 devnull if the note was recognized (and resolved);
144 cfa37a7b 2004-04-10 devnull otherwise it must return zero.
145 cfa37a7b 2004-04-10 devnull When the system posts a note to the process,
146 cfa37a7b 2004-04-10 devnull each handler registered with
147 cfa37a7b 2004-04-10 devnull .I atnotify
148 cfa37a7b 2004-04-10 devnull is called with arguments as
149 cfa37a7b 2004-04-10 devnull described above
150 cfa37a7b 2004-04-10 devnull until one of the handlers returns non-zero.
152 cfa37a7b 2004-04-10 devnull .I noted
153 cfa37a7b 2004-04-10 devnull is called with argument
154 cfa37a7b 2004-04-10 devnull .BR NCONT .
155 cfa37a7b 2004-04-10 devnull If no registered function returns non-zero,
156 cfa37a7b 2004-04-10 devnull .I atnotify
158 cfa37a7b 2004-04-10 devnull .I noted
159 cfa37a7b 2004-04-10 devnull with argument
160 cfa37a7b 2004-04-10 devnull .BR NDFLT .
162 cfa37a7b 2004-04-10 devnull .I Noted
163 cfa37a7b 2004-04-10 devnull has two other possible values for its argument.
164 cfa37a7b 2004-04-10 devnull .B NSAVE
165 cfa37a7b 2004-04-10 devnull returns from the handler and clears the note, enabling the receipt of another,
166 cfa37a7b 2004-04-10 devnull but does not return to the program.
167 cfa37a7b 2004-04-10 devnull Instead it starts a new handler with the same stack, stack pointer,
168 cfa37a7b 2004-04-10 devnull and arguments as the
169 cfa37a7b 2004-04-10 devnull original, at the address recorded in the program counter of the
171 cfa37a7b 2004-04-10 devnull structure. Typically, the program counter will be overridden by the
172 cfa37a7b 2004-04-10 devnull first note handler to be the address of a separate function;
173 cfa37a7b 2004-04-10 devnull .B NSAVE
174 cfa37a7b 2004-04-10 devnull is then a `trampoline' to that handler.
175 cfa37a7b 2004-04-10 devnull That handler may executed
176 cfa37a7b 2004-04-10 devnull .B noted(NRSTR)
177 cfa37a7b 2004-04-10 devnull to return to the original program, usually after restoring the original program
178 cfa37a7b 2004-04-10 devnull counter.
179 cfa37a7b 2004-04-10 devnull .B NRSTR
180 cfa37a7b 2004-04-10 devnull is identical to
181 cfa37a7b 2004-04-10 devnull .BR NCONT
182 cfa37a7b 2004-04-10 devnull except that it can only be executed after an
183 cfa37a7b 2004-04-10 devnull .BR NSAVE .
184 cfa37a7b 2004-04-10 devnull .B NSAVE
186 cfa37a7b 2004-04-10 devnull .B NRSTR
187 cfa37a7b 2004-04-10 devnull are designed to improve the emulation of signals by the ANSI C/POSIX
188 cfa37a7b 2004-04-10 devnull environment; their use elsewhere is discouraged.
190 cfa37a7b 2004-04-10 devnull The set of notes a process may receive is system-dependent, but there
191 cfa37a7b 2004-04-10 devnull is a common set that includes:
195 cfa37a7b 2004-04-10 devnull .ta \w'\fLsys: write on closed pipe \fP'u
196 cfa37a7b 2004-04-10 devnull \fINote\fP \fIMeaning\fP
197 cfa37a7b 2004-04-10 devnull \fLinterrupt\fP user interrupt (DEL key)
198 cfa37a7b 2004-04-10 devnull \fLhangup\fP I/O connection closed
199 cfa37a7b 2004-04-10 devnull \fLalarm\fP alarm expired
200 cfa37a7b 2004-04-10 devnull \fLsys: breakpoint\fP breakpoint instruction
201 cfa37a7b 2004-04-10 devnull \fLsys: bad address\fP system call address argument out of range
202 cfa37a7b 2004-04-10 devnull \fLsys: odd address\fP system call address argument unaligned
203 cfa37a7b 2004-04-10 devnull \fLsys: bad sys call\fP system call number out of range
204 cfa37a7b 2004-04-10 devnull \fLsys: odd stack\fP system call user stack unaligned
205 cfa37a7b 2004-04-10 devnull \fLsys: write on closed pipe\fP write on closed pipe
206 cfa37a7b 2004-04-10 devnull \fLsys: fp: \fIfptrap\f1 floating point exception
207 cfa37a7b 2004-04-10 devnull \fLsys: trap: \fItrap\f1 other exception (see below)
211 cfa37a7b 2004-04-10 devnull The notes prefixed
213 cfa37a7b 2004-04-10 devnull are generated by the operating system.
214 cfa37a7b 2004-04-10 devnull They are suffixed by the user program counter in format
215 cfa37a7b 2004-04-10 devnull .BR pc=0x1234 .
216 cfa37a7b 2004-04-10 devnull If the note is due to a floating point exception, just before the
218 cfa37a7b 2004-04-10 devnull is the address of the offending instruction in format
219 cfa37a7b 2004-04-10 devnull .BR fppc=0x1234 .
220 cfa37a7b 2004-04-10 devnull Notes are limited to
221 cfa37a7b 2004-04-10 devnull .B ERRLEN
222 cfa37a7b 2004-04-10 devnull bytes; if they would be longer they are truncated but the
224 cfa37a7b 2004-04-10 devnull is always reported correctly.
226 cfa37a7b 2004-04-10 devnull The types and syntax of the
229 cfa37a7b 2004-04-10 devnull .I fptrap
230 cfa37a7b 2004-04-10 devnull portions of the notes are machine-dependent.
231 cfa37a7b 2004-04-10 devnull .SH SOURCE
232 b5fdffee 2004-04-19 devnull .B /usr/local/plan9/src/libc/9syscall
234 b5fdffee 2004-04-19 devnull .B /usr/local/plan9/src/libc/port/atnotify.c
235 cfa37a7b 2004-04-10 devnull .SH SEE ALSO
236 bf8a59fa 2004-04-11 devnull .IR intro (3),
237 cfa37a7b 2004-04-10 devnull .I notejmp
239 bf8a59fa 2004-04-11 devnull .IR setjmp (3)
240 cfa37a7b 2004-04-10 devnull .SH BUGS
242 bf8a59fa 2004-04-11 devnull .IR exec (3)
243 cfa37a7b 2004-04-10 devnull discards the notification handler, there is a window
244 cfa37a7b 2004-04-10 devnull of vulnerability to notes in a new process.
