| <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> |
