NOTIFY(3) NOTIFY(3)
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 opera-
tions.
After a note is posted, the handler is called with two argu-
ments: 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
Page 1 Plan 9 (printed 11/18/24)
NOTIFY(3) NOTIFY(3)
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 han-
dlers. The parameter in is non-zero to register the func-
tion 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.
Notify and atnotify return -1 on error and 0 on success.
Noted returns -1 on error; successful calls to noted do not
return. Noteenable and notedisable (notitfyon and
notifyoff) return -1 on error, 0 if the note was previously
disabled (not notified), and 1 if the note was previously
enabled (notified).
The set of notes a process may receive is system-dependent,
but there is a common set that includes:
Page 2 Plan 9 (printed 11/18/24)
NOTIFY(3) NOTIFY(3)
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 operat-
ing system.
SOURCE
/usr/local/plan9/src/lib9/notify.c
/usr/local/plan9/src/lib9/atnotify.c
SEE ALSO
intro(3), notejmp in setjmp(3)
Page 3 Plan 9 (printed 11/18/24)