3 notify, noted, atnotify \- handle asynchronous process notification
10 int notify(void (*f)(void*, char*))
16 int atnotify(int (*f)(void*, char*), int in)
18 When a process raises an exceptional condition such as dividing by zero
19 or writing on a closed pipe, a
21 is posted to communicate the exception.
22 A note may also be posted by a
30 file of a process in the same process group (see
32 When the note is received
33 the behavior of the process depends on the origin of the note.
34 If the note was posted by an external process,
35 the process receiving the note exits;
36 if generated by the system the note string,
38 and id of the process and the string
40 is printed on the process's standard error file
42 process is suspended in the
46 These default actions may be overridden.
50 .I "notification handler
51 to be called within the process when a note is received.
54 replaces the previous handler, if any.
55 An argument of zero cancels a previous handler,
56 restoring the default action.
59 system call leaves the handler registered in
60 both the parent and the child;
62 restores the default behavior.
63 Handlers may not perform floating point operations.
65 After a note is posted,
66 the handler is called with two arguments:
67 the first is a pointer to a
70 .BR /$objtype/include/ureg.h )
71 giving the current values of registers;
72 the second is a pointer to the note itself,
73 a null-terminated string with no more than
75 characters in it including the terminal NUL.
78 argument is usually not needed; it is provided to help recover from traps such
79 as floating point exceptions.
80 Its use and layout are machine- and system-specific.
82 A notification handler must finish either by exiting the program or by calling
84 if the handler returns the behavior
85 is undefined and probably erroneous.
86 Until the program calls
88 any further externally-generated notes
93 will be held off, and any further notes generated by
94 erroneous behavior by the program
95 (such as divide by zero) will kill the program.
98 defines the action to take:
100 instructs the system to perform the default action
101 as if the handler had never been registered;
103 instructs the system to resume the process
104 at the point it was notified.
107 return to the handler.
108 If the note interrupted an incomplete system call,
109 that call returns an error (with error string
111 after the process resumes.
112 A notification handler can also jump out to an environment
119 which is implemented by modifying the saved state and calling
122 Regardless of the origin of the note or the presence of a handler,
123 if the process is being debugged
126 the arrival of a note puts the process in the
128 state and awakens the debugger.
130 Rather than using the system calls
134 most programs should use
136 to register notification handlers.
139 is non-zero to register the function
141 and zero to cancel registration.
142 A handler must return a non-zero number
143 if the note was recognized (and resolved);
144 otherwise it must return zero.
145 When the system posts a note to the process,
146 each handler registered with
148 is called with arguments as
150 until one of the handlers returns non-zero.
153 is called with argument
155 If no registered function returns non-zero,
163 has two other possible values for its argument.
165 returns from the handler and clears the note, enabling the receipt of another,
166 but does not return to the program.
167 Instead it starts a new handler with the same stack, stack pointer,
169 original, at the address recorded in the program counter of the
171 structure. Typically, the program counter will be overridden by the
172 first note handler to be the address of a separate function;
174 is then a `trampoline' to that handler.
175 That handler may executed
177 to return to the original program, usually after restoring the original program
182 except that it can only be executed after an
187 are designed to improve the emulation of signals by the ANSI C/POSIX
188 environment; their use elsewhere is discouraged.
190 The set of notes a process may receive is system-dependent, but there
191 is a common set that includes:
195 .ta \w'\fLsys: write on closed pipe \fP'u
196 \fINote\fP \fIMeaning\fP
197 \fLinterrupt\fP user interrupt (DEL key)
198 \fLhangup\fP I/O connection closed
199 \fLalarm\fP alarm expired
200 \fLsys: breakpoint\fP breakpoint instruction
201 \fLsys: bad address\fP system call address argument out of range
202 \fLsys: odd address\fP system call address argument unaligned
203 \fLsys: bad sys call\fP system call number out of range
204 \fLsys: odd stack\fP system call user stack unaligned
205 \fLsys: write on closed pipe\fP write on closed pipe
206 \fLsys: fp: \fIfptrap\f1 floating point exception
207 \fLsys: trap: \fItrap\f1 other exception (see below)
213 are generated by the operating system.
214 They are suffixed by the user program counter in format
216 If the note is due to a floating point exception, just before the
218 is the address of the offending instruction in format
222 bytes; if they would be longer they are truncated but the
224 is always reported correctly.
226 The types and syntax of the
230 portions of the notes are machine-dependent.
232 .B /sys/src/libc/9syscall
234 .B /sys/src/libc/port/atnotify.c
244 discards the notification handler, there is a window
245 of vulnerability to notes in a new process.