1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
|
<head>
<title>notify(3) - Plan 9 from User Space</title>
<meta content="text/html; charset=utf-8" http-equiv=Content-Type>
</head>
<body bgcolor=#ffffff>
<table border=0 cellpadding=0 cellspacing=0 width=100%>
<tr height=10><td>
<tr><td width=20><td>
<tr><td width=20><td><b>NOTIFY(3)</b><td align=right><b>NOTIFY(3)</b>
<tr><td width=20><td colspan=2>
<br>
<p><font size=+1><b>NAME </b></font><br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
notify, noted, atnotify, noteenable, notedisable, notifyon, notifyoff
– handle asynchronous process notification<br>
</table>
<p><font size=+1><b>SYNOPSIS </b></font><br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
<tt><font size=+1>#include <u.h><br>
#include <libc.h>
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
<tt><font size=+1>int notify(void (*f)(void*, char*))
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
<tt><font size=+1>int noted(int v)
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
<tt><font size=+1>int atnotify(int (*f)(void*, char*), int in)
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
<tt><font size=+1>int noteenable(char *msg)<br>
int notedisable(char *msg)
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
<tt><font size=+1>int notifyon(char *msg)<br>
int notifyoff(char *msg)<br>
</font></tt>
</table>
<p><font size=+1><b>DESCRIPTION </b></font><br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
When a process raises an exceptional condition such as dividing
by zero or writing on a closed pipe, a <i>note</i> is posted to communicate
the exception. A note may also be posted by another process via
<a href="../man3/postnote.html"><i>postnote</i>(3)</a>. On Unix, notes are implemented as signals.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
When a note is received, the action taken depends on the note.
See <a href="../man7/signal.html"><i>signal</i>(7)</a> for the full description of the defaults.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
The default actions may be overridden. The <i>notify</i> function registers
a <i>notification handler</i> to be called within the process when a
note is received. The argument to <i>notify</i> replaces the previous
handler, if any. An argument of zero cancels a previous handler,
restoring the default action. A <a href="../man2/fork.html"><i>fork</i>(2)</a> system call leaves the
handler registered in both the parent and the child; <a href="../man3/exec.html"><i>exec</i>(3)</a> restores
the default behavior. Handlers may not perform floating point
operations.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
After a note is posted, the handler is called with two arguments:
the first is unimplemented and should not be used (on Plan 9 it
is a <tt><font size=+1>Ureg</font></tt> structure giving the current values of registers); the
second is a pointer to the note itself, a null-terminated string.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
A notification handler must finish either by exiting the program
or by calling <i>noted</i>; if the handler returns the behavior is undefined
and probably erroneous. Until the program calls <i>noted</i>, any further
externally-generated notes (e.g., <tt><font size=+1>hangup</font></tt> or <tt><font size=+1>alarm</font></tt>) will be held
off, and any further notes generated by erroneous
behavior by the program (such as divide by zero) will kill the
program. The argument to <i>noted</i> defines the action to take: <tt><font size=+1>NDFLT</font></tt>
instructs the system to perform the default action as if the handler
had never been registered; <tt><font size=+1>NCONT</font></tt> instructs the system to resume
the process at the point it was notified. In neither case
does <i>noted</i> return to the handler. If the note interrupted an incomplete
system call, that call returns an error (with error string <tt><font size=+1>interrupted</font></tt>)
after the process resumes. A notification handler can also jump
out to an environment set up with <i>setjmp</i> using the <i>notejmp</i> function
(see <a href="../man3/setjmp.html"><i>setjmp</i>(3)</a>).
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
Unix provides a fixed set of notes (typically there are 32) called
<i>signals</i>. It also allows a process to block certain notes from
being delivered (see <a href="../man2/sigprocmask.html"><i>sigprocmask</i>(2)</a>) and to ignore certain notes
by setting the signal hander to the special value <tt><font size=+1>SIG_IGN</font></tt> (see
<a href="../man2/signal.html"><i>signal</i>(2)</a>). <i>Noteenable</i> and <i>notedisable</i> enable or disable receipt
of
a particular note by changing the current process’s blocked signal
mask. Receipt of a disabled note will be postponed until it is
reenabled. <i>Notifyon</i> and <i>notifyoff</i> enable or disable whether the
notification handler is called upon receipt of the note; if the
handler is not called, the note is discarded.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
Regardless of the origin of the note or the presence of a handler,
if the process is being debugged (see <a href="../man2/ptrace.html"><i>ptrace</i>(2)</a>) the arrival of
a note puts the process in the <tt><font size=+1>Stopped</font></tt> state and awakens the debugger.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
Rather than using the system calls <i>notify</i> and <i>noted</i>, most programs
should use <i>atnotify</i> to register notification handlers. The parameter
<i>in</i> is non-zero to register the function <i>f</i>, and zero to cancel
registration. A handler must return a non-zero number if the note
was recognized (and resolved); otherwise it must return
zero. When the system posts a note to the process, each handler
registered with <i>atnotify</i> is called with arguments as described
above until one of the handlers returns non-zero. Then <i>noted</i> is
called with argument <tt><font size=+1>NCONT</font></tt>. If no registered function returns
non-zero, <i>atnotify</i> calls <i>noted</i> with argument <tt><font size=+1>NDFLT</font></tt>.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
The set of notes a process may receive is system-dependent, but
there is a common set that includes:
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
<i>Note Meaning Unix signal<br>
</i><tt><font size=+1>interrupt </font></tt> user interrupt (DEL key) SIGINTR<br>
<tt><font size=+1>hangup </font></tt> I/O connection closed SIGHUP<br>
<tt><font size=+1>alarm </font></tt> alarm expired SIGLARM<br>
<tt><font size=+1>quit </font></tt> quit from keyboard SIGQUIT<br>
<tt><font size=+1>kill </font></tt> process requested to exit SIGTERM<br>
<tt><font size=+1>sys: kill </font></tt> process forced to exit SIGKILL<br>
<tt><font size=+1>sys: bus error </font></tt> bus error SIGBUS<br>
<tt><font size=+1>sys: segmentation violation </font></tt> segmentation violation SIGSEGV<br>
<tt><font size=+1>sys: write on closed pipe </font></tt> write on closed pipe SIGPIPE<br>
<tt><font size=+1>sys: child </font></tt> child wait status change SIGCHLD<br>
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</table>
See <tt><font size=+1>/usr/local/plan9/src/lib9/await.c</font></tt> (sic) for the full list.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
The notes prefixed <tt><font size=+1>sys:</font></tt> are usually generated by the operating
system.<br>
</table>
<p><font size=+1><b>SOURCE </b></font><br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
<tt><font size=+1>/usr/local/plan9/src/lib9/notify.c<br>
/usr/local/plan9/src/lib9/atnotify.c<br>
</font></tt>
</table>
<p><font size=+1><b>SEE ALSO </b></font><br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
<a href="../man3/intro.html"><i>intro</i>(3)</a>, <i>notejmp</i> in <a href="../man3/setjmp.html"><i>setjmp</i>(3)</a><br>
</table>
<td width=20>
<tr height=20><td>
</table>
<!-- TRAILER -->
<table border=0 cellpadding=0 cellspacing=0 width=100%>
<tr height=15><td width=10><td><td width=10>
<tr><td><td>
<center>
<a href="../../"><img src="../../dist/spaceglenda100.png" alt="Space Glenda" border=1></a>
</center>
</table>
<!-- TRAILER -->
</body></html>
|