NOTIFY(2) NOTIFY(2)
NAME
notify, noted, atnotify - handle asynchronous process
notification
SYNOPSIS
int notify(void (*f)(void*, char*))
int noted(int v)
int atnotify(int (*f)(void*, char*), int in)
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 a write(see read(2)) to the process's /proc/n/note
file or to the /proc/m/notepg file of a process in the same
process group (see proc(3)). When the note is received the
behavior of the process depends on the origin of the note.
If the note was posted by an external process, the process
receiving the note exits; if generated by the system the
note string, preceded by the name and id of the process and
the string "suicide: ", is printed on the process's standard
error file and the process is suspended in the Broken state
for debugging.
These default actions may be overridden. The notify func-
tion 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(2) restores the default
behavior.
After a note is posted, the handler is called with two argu-
ments: the first is a pointer to a Ureg structure (defined
in /$objtype/include/ureg.h) giving the current values of
registers; the second is a pointer to the note itself, a
null-terminated string with no more than `ERRLEN' characters
in it including the terminal NUL. The Ureg argument is usu-
ally not needed; it is provided to help recover from traps
such as floating point exceptions. Its use and layout are
machine- and system-specific.
A notification handler must finish by calling noted; if the
handler returns the behavior is undefined and probably erro-
neous. 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
Page 1 Plan 9 (printed 11/18/24)
NOTIFY(2) NOTIFY(2)
the system to resume the process at the point it was noti-
fied. 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 func-
tion (see setjmp(2)).
Regardless of the origin of the note or the presence of a
handler, if the process is being debugged (see proc(3)) 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.
The set of notes a process may receive is system-dependent,
but there is a common set that includes:
Note Meaning
interrupt user interrupt (DEL key)
hangup I/O connection closed
alarm alarm expired
sys: breakpoint breakpoint instruction
sys: bad address system call address argument out of range
sys: odd address system call address argument unaligned
sys: bad sys call system call number out of range
sys: odd stack system call user stack unaligned
sys: write on closed pipe write on closed pipe
sys: fp: fptrap floating point exception
sys: trap: trap other exception (see below)
The notes prefixed sys: are generated by the operating sys-
tem. They are suffixed by the user program counter in for-
mat pc=0x1234. If the note is due to a floating point
exception, just before the pc is the address of the offend-
ing instruction in format fppc=0x1234. Notes are limited to
ERRLEN bytes; if they would be longer they are truncated but
the pc is always reported correctly.
The types and syntax of the trap and fptrap portions of the
notes are machine-dependent.
Page 2 Plan 9 (printed 11/18/24)
NOTIFY(2) NOTIFY(2)
SEE ALSO
intro(2), notejmp in setjmp(2)
BUGS
Since exec(2) discards the notification handler, there is a
window of vulnerability to notes in a new process.
Page 3 Plan 9 (printed 11/18/24)