183 lines
11 KiB
HTML
183 lines
11 KiB
HTML
<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>
|