Some man pages.
This commit is contained in:
rsc
parent
2600337aa7
commit
058b0118a5
214 changed files with 17112 additions and 1999 deletions
|
|
@ -1,6 +1,6 @@
|
|||
.TH NOTIFY 3
|
||||
.SH NAME
|
||||
notify, noted, atnotify \- handle asynchronous process notification
|
||||
notify, noted, atnotify, noteenable, notedisable, notifyon, notifyoff \- handle asynchronous process notification
|
||||
.SH SYNOPSIS
|
||||
.B #include <u.h>
|
||||
.br
|
||||
|
|
@ -14,36 +14,34 @@ int noted(int v)
|
|||
.PP
|
||||
.B
|
||||
int atnotify(int (*f)(void*, char*), int in)
|
||||
.PP
|
||||
.B
|
||||
int noteenable(char *msg)
|
||||
.br
|
||||
.B
|
||||
int notedisable(char *msg)
|
||||
.PP
|
||||
.B
|
||||
int notifyon(char *msg)
|
||||
.br
|
||||
.B
|
||||
int notifyoff(char *msg)
|
||||
.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 (3))
|
||||
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.
|
||||
A note may also be posted by another process
|
||||
via
|
||||
.IR postnote (3).
|
||||
On Unix, notes are implemented as signals.
|
||||
.PP
|
||||
These default actions may be overridden.
|
||||
When a note is received, the action taken depends on the note.
|
||||
See
|
||||
.IR signal (7)
|
||||
for the full description of the defaults.
|
||||
.PP
|
||||
The default actions may be overridden.
|
||||
The
|
||||
.I notify
|
||||
function registers a
|
||||
|
|
@ -55,7 +53,7 @@ replaces the previous handler, if any.
|
|||
An argument of zero cancels a previous handler,
|
||||
restoring the default action.
|
||||
A
|
||||
.IR fork (3)
|
||||
.IR fork (2)
|
||||
system call leaves the handler registered in
|
||||
both the parent and the child;
|
||||
.IR exec (3)
|
||||
|
|
@ -64,20 +62,19 @@ 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
|
||||
the first is unimplemented and should not be used
|
||||
(on Plan 9
|
||||
it is a
|
||||
.B Ureg
|
||||
structure (defined in
|
||||
.BR /$objtype/include/ureg.h )
|
||||
giving the current values of registers;
|
||||
structure
|
||||
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.
|
||||
a null-terminated string.
|
||||
.\" 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 ;
|
||||
|
|
@ -115,14 +112,32 @@ set up with
|
|||
using the
|
||||
.I notejmp
|
||||
function (see
|
||||
.IR setjmp (3)),
|
||||
which is implemented by modifying the saved state and calling
|
||||
.BR noted(NCONT) .
|
||||
.IR setjmp (3)).
|
||||
.PP
|
||||
Unix provides a fixed set of notes (typically there are 32) called
|
||||
.IR signals .
|
||||
It also allows a process to block certain notes from being delivered
|
||||
(see
|
||||
.IR sigprocmask (2))
|
||||
and to ignore certain notes by setting the signal hander to the special value
|
||||
.B SIG_IGN
|
||||
(see
|
||||
.IR signal (2)).
|
||||
.I Noteenable
|
||||
and
|
||||
.I 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.
|
||||
.I Notifyon
|
||||
and
|
||||
.I 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.
|
||||
.PP
|
||||
Regardless of the origin of the note or the presence of a handler,
|
||||
if the process is being debugged
|
||||
(see
|
||||
.IR proc (3))
|
||||
.IR ptrace (2))
|
||||
the arrival of a note puts the process in the
|
||||
.B Stopped
|
||||
state and awakens the debugger.
|
||||
|
|
@ -158,87 +173,67 @@ 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
|
||||
.\" .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)
|
||||
.ta \w'\fLsys: write on closed pipe \fP'u \w'system call address argument out of range 'u
|
||||
\fINote\fP \fIMeaning\fP \fIUnix signal\fP
|
||||
\fLinterrupt\fP user interrupt (DEL key) SIGINTR
|
||||
\fLhangup\fP I/O connection closed SIGHUP
|
||||
\fLalarm\fP alarm expired SIGLARM
|
||||
\fLquit\fP quit from keyboard SIGQUIT
|
||||
\fLkill\fP process requested to exit SIGTERM
|
||||
\fLsys: kill\fP process forced to exit SIGKILL
|
||||
\fLsys: bus error\fP bus error SIGBUS
|
||||
\fLsys: segmentation violation\fP segmentation violation SIGSEGV
|
||||
.fi
|
||||
.RE
|
||||
.PP
|
||||
See
|
||||
.B /usr/local/plan9/src/lib9/await.c
|
||||
(sic)
|
||||
for the full list.
|
||||
.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.
|
||||
are usually generated by the operating system.
|
||||
.SH SOURCE
|
||||
.B /usr/local/plan9/src/libc/9syscall
|
||||
.B /usr/local/plan9/src/lib9/notify.c
|
||||
.br
|
||||
.B /usr/local/plan9/src/libc/port/atnotify.c
|
||||
.B /usr/local/plan9/src/lib9/atnotify.c
|
||||
.SH SEE ALSO
|
||||
.IR intro (3),
|
||||
.I notejmp
|
||||
in
|
||||
.IR setjmp (3)
|
||||
.SH BUGS
|
||||
Since
|
||||
.IR exec (3)
|
||||
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