|
NAME
| |
notify, noted, atnotify, noteenable, notedisable, notifyon, notifyoff
– handle asynchronous process notification
|
SYNOPSIS
| |
#include <u.h>
#include <libc.h>
int notify(void (*f)(void*, char*))
int noted(int v)
int atnotify(int (*f)(void*, char*), int in)
int noteenable(char *msg)
int notedisable(char *msg)
int notifyon(char *msg)
int notifyoff(char *msg)
|
DESCRIPTION
| |
When a process raises an exceptional condition such as dividing
by zero or writing on a closed pipe, a note is posted to communicate
the exception. A note may also be posted by another process via
postnote(3). On Unix, notes are implemented as signals.
When a note is received, the action taken depends on the note.
See signal(7) for the full description of the defaults.
The default actions may be overridden. The notify function registers
a notification handler to be called within the process when a
note is received. The argument to notify replaces the previous
handler, if any. An argument of zero cancels a previous handler,
restoring the default action. A fork(2) system call leaves the
handler registered in both the parent and the child; exec(3) restores
the default behavior. Handlers may not perform floating point
operations.
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 Ureg structure giving the current values of registers); the
second is a pointer to the note itself, a null-terminated string.
A notification handler must finish either by exiting the program
or by calling noted; if the handler returns the behavior is undefined
and probably erroneous. Until the program calls noted, any further
externally-generated notes (e.g., hangup or alarm) 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 noted defines the action to take: NDFLT
instructs the system to perform the default action as if the handler
had never been registered; NCONT instructs the system to resume
the process at the point it was notified. In neither case
does noted return to the handler. If the note interrupted an incomplete
system call, that call returns an error (with error string interrupted)
after the process resumes. A notification handler can also jump
out to an environment set up with setjmp using the notejmp function
(see setjmp(3)).
Unix provides a fixed set of notes (typically there are 32) called
signals. It also allows a process to block certain notes from
being delivered (see sigprocmask(2)) and to ignore certain notes
by setting the signal hander to the special value SIG_IGN (see
signal(2)). Noteenable and notedisable 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. Notifyon and notifyoff enable or disable whether the
notification handler is called upon receipt of the note; if the
handler is not called, the note is discarded.
Regardless of the origin of the note or the presence of a handler,
if the process is being debugged (see ptrace(2)) the arrival of
a note puts the process in the Stopped state and awakens the debugger.
Rather than using the system calls notify and noted, most programs
should use atnotify to register notification handlers. The parameter
in is non-zero to register the function f, 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 atnotify is called with arguments as described
above until one of the handlers returns non-zero. Then noted is
called with argument NCONT. If no registered function returns
non-zero, atnotify calls noted with argument NDFLT.
The set of notes a process may receive is system-dependent, but
there is a common set that includes:
| |
Note Meaning Unix signal
interrupt user interrupt (DEL key) SIGINTR
hangup I/O connection closed SIGHUP
alarm alarm expired SIGLARM
quit quit from keyboard SIGQUIT
kill process requested to exit SIGTERM
sys: kill process forced to exit SIGKILL
sys: bus error bus error SIGBUS
sys: segmentation violation segmentation violation SIGSEGV
sys: write on closed pipe write on closed pipe SIGPIPE
sys: child child wait status change SIGCHLD
|
See /usr/local/plan9/src/lib9/await.c (sic) for the full list.
The notes prefixed sys: are usually generated by the operating
system.
|
SOURCE
| |
/usr/local/plan9/src/lib9/notify.c
/usr/local/plan9/src/lib9/atnotify.c
|
SEE ALSO
|
|