tnotify.3 - plan9port - [fork] Plan 9 from user space
(HTM) git clone git://src.adamsgaard.dk/plan9port
(DIR) Log
(DIR) Files
(DIR) Refs
(DIR) README
(DIR) LICENSE
---
tnotify.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)