Lots of man pages.
This commit is contained in:
rsc
parent
08df2a433e
commit
cfa37a7b11
152 changed files with 25407 additions and 148 deletions
244
man/man3/notify.3
Normal file
244
man/man3/notify.3
Normal file
|
|
@ -0,0 +1,244 @@
|
|||
.TH NOTIFY 3
|
||||
.SH NAME
|
||||
notify, noted, atnotify \- handle asynchronous process notification
|
||||
.SH SYNOPSIS
|
||||
.B #include <u.h>
|
||||
.br
|
||||
.B #include <libc.h>
|
||||
.PP
|
||||
.B
|
||||
int notify(void (*f)(void*, char*))
|
||||
.PP
|
||||
.B
|
||||
int noted(int v)
|
||||
.PP
|
||||
.B
|
||||
int atnotify(int (*f)(void*, char*), int in)
|
||||
.SH DESCRIPTION
|
||||
When a process raises an exceptional condition such as dividing by zero
|
||||
or writing on a closed pipe, a
|
||||
.I note
|
||||
is posted to communicate the exception.
|
||||
A note may also be posted by a
|
||||
.I write
|
||||
(see
|
||||
.IR read (2))
|
||||
to the process's
|
||||
.BI /proc/ n /note
|
||||
file or to the
|
||||
.BI /proc/ m /notepg
|
||||
file of a process in the same process group (see
|
||||
.IR 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
|
||||
\fL"suicide: "\fP,
|
||||
is printed on the process's standard error file
|
||||
and the
|
||||
process is suspended in the
|
||||
.B Broken
|
||||
state for debugging.
|
||||
.PP
|
||||
These default actions may be overridden.
|
||||
The
|
||||
.I notify
|
||||
function registers a
|
||||
.I "notification handler
|
||||
to be called within the process when a note is received.
|
||||
The argument to
|
||||
.I notify
|
||||
replaces the previous handler, if any.
|
||||
An argument of zero cancels a previous handler,
|
||||
restoring the default action.
|
||||
A
|
||||
.IR fork (2)
|
||||
system call leaves the handler registered in
|
||||
both the parent and the child;
|
||||
.IR exec (2)
|
||||
restores the default behavior.
|
||||
Handlers may not perform floating point operations.
|
||||
.PP
|
||||
After a note is posted,
|
||||
the handler is called with two arguments:
|
||||
the first is a pointer to a
|
||||
.B Ureg
|
||||
structure (defined in
|
||||
.BR /$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
|
||||
.L ERRLEN
|
||||
characters in it including the terminal NUL.
|
||||
The
|
||||
.B Ureg
|
||||
argument is usually not needed; it is provided to help recover from traps such
|
||||
as floating point exceptions.
|
||||
Its use and layout are machine- and system-specific.
|
||||
.PP
|
||||
A notification handler must finish either by exiting the program or by calling
|
||||
.IR noted ;
|
||||
if the handler returns the behavior
|
||||
is undefined and probably erroneous.
|
||||
Until the program calls
|
||||
.IR noted ,
|
||||
any further externally-generated notes
|
||||
(e.g.,
|
||||
.B hangup
|
||||
or
|
||||
.BR 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
|
||||
.I noted
|
||||
defines the action to take:
|
||||
.B NDFLT
|
||||
instructs the system to perform the default action
|
||||
as if the handler had never been registered;
|
||||
.B NCONT
|
||||
instructs the system to resume the process
|
||||
at the point it was notified.
|
||||
In neither case does
|
||||
.I noted
|
||||
return to the handler.
|
||||
If the note interrupted an incomplete system call,
|
||||
that call returns an error (with error string
|
||||
.BR interrupted )
|
||||
after the process resumes.
|
||||
A notification handler can also jump out to an environment
|
||||
set up with
|
||||
.I setjmp
|
||||
using the
|
||||
.I notejmp
|
||||
function (see
|
||||
.IR setjmp (2)),
|
||||
which is implemented by modifying the saved state and calling
|
||||
.BR noted(NCONT) .
|
||||
.PP
|
||||
Regardless of the origin of the note or the presence of a handler,
|
||||
if the process is being debugged
|
||||
(see
|
||||
.IR proc (3))
|
||||
the arrival of a note puts the process in the
|
||||
.B Stopped
|
||||
state and awakens the debugger.
|
||||
.PP
|
||||
Rather than using the system calls
|
||||
.I notify
|
||||
and
|
||||
.IR noted ,
|
||||
most programs should use
|
||||
.I atnotify
|
||||
to register notification handlers.
|
||||
The parameter
|
||||
.I in
|
||||
is non-zero to register the function
|
||||
.IR 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
|
||||
.I atnotify
|
||||
is called with arguments as
|
||||
described above
|
||||
until one of the handlers returns non-zero.
|
||||
Then
|
||||
.I noted
|
||||
is called with argument
|
||||
.BR NCONT .
|
||||
If no registered function returns non-zero,
|
||||
.I atnotify
|
||||
calls
|
||||
.I noted
|
||||
with argument
|
||||
.BR NDFLT .
|
||||
.PP
|
||||
.I Noted
|
||||
has two other possible values for its argument.
|
||||
.B NSAVE
|
||||
returns from the handler and clears the note, enabling the receipt of another,
|
||||
but does not return to the program.
|
||||
Instead it starts a new handler with the same stack, stack pointer,
|
||||
and arguments as the
|
||||
original, at the address recorded in the program counter of the
|
||||
.B Ureg
|
||||
structure. Typically, the program counter will be overridden by the
|
||||
first note handler to be the address of a separate function;
|
||||
.B NSAVE
|
||||
is then a `trampoline' to that handler.
|
||||
That handler may executed
|
||||
.B noted(NRSTR)
|
||||
to return to the original program, usually after restoring the original program
|
||||
counter.
|
||||
.B NRSTR
|
||||
is identical to
|
||||
.BR NCONT
|
||||
except that it can only be executed after an
|
||||
.BR NSAVE .
|
||||
.B NSAVE
|
||||
and
|
||||
.B NRSTR
|
||||
are designed to improve the emulation of signals by the ANSI C/POSIX
|
||||
environment; their use elsewhere is discouraged.
|
||||
.PP
|
||||
The set of notes a process may receive is system-dependent, but there
|
||||
is a common set that includes:
|
||||
.PP
|
||||
.RS 3n
|
||||
.nf
|
||||
.ta \w'\fLsys: write on closed pipe \fP'u
|
||||
\fINote\fP \fIMeaning\fP
|
||||
\fLinterrupt\fP user interrupt (DEL key)
|
||||
\fLhangup\fP I/O connection closed
|
||||
\fLalarm\fP alarm expired
|
||||
\fLsys: breakpoint\fP breakpoint instruction
|
||||
\fLsys: bad address\fP system call address argument out of range
|
||||
\fLsys: odd address\fP system call address argument unaligned
|
||||
\fLsys: bad sys call\fP system call number out of range
|
||||
\fLsys: odd stack\fP system call user stack unaligned
|
||||
\fLsys: write on closed pipe\fP write on closed pipe
|
||||
\fLsys: fp: \fIfptrap\f1 floating point exception
|
||||
\fLsys: trap: \fItrap\f1 other exception (see below)
|
||||
.fi
|
||||
.RE
|
||||
.PP
|
||||
The notes prefixed
|
||||
.B sys:
|
||||
are generated by the operating system.
|
||||
They are suffixed by the user program counter in format
|
||||
.BR pc=0x1234 .
|
||||
If the note is due to a floating point exception, just before the
|
||||
.BR pc
|
||||
is the address of the offending instruction in format
|
||||
.BR fppc=0x1234 .
|
||||
Notes are limited to
|
||||
.B ERRLEN
|
||||
bytes; if they would be longer they are truncated but the
|
||||
.B pc
|
||||
is always reported correctly.
|
||||
.PP
|
||||
The types and syntax of the
|
||||
.I trap
|
||||
and
|
||||
.I fptrap
|
||||
portions of the notes are machine-dependent.
|
||||
.SH SOURCE
|
||||
.B /sys/src/libc/9syscall
|
||||
.br
|
||||
.B /sys/src/libc/port/atnotify.c
|
||||
.SH SEE ALSO
|
||||
.IR intro (2),
|
||||
.I notejmp
|
||||
in
|
||||
.IR setjmp (2)
|
||||
.SH BUGS
|
||||
Since
|
||||
.IR exec (2)
|
||||
discards the notification handler, there is a window
|
||||
of vulnerability to notes in a new process.
|
||||
Loading…
Add table
Add a link
Reference in a new issue