diff options
Diffstat (limited to 'man/man3/notify.html')
| -rw-r--r-- | man/man3/notify.html | 183 |
1 files changed, 183 insertions, 0 deletions
diff --git a/man/man3/notify.html b/man/man3/notify.html new file mode 100644 index 00000000..9899e701 --- /dev/null +++ b/man/man3/notify.html @@ -0,0 +1,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> |