Some man pages.

1 files changed, 104 insertions, 109 deletions

diff --git a/man/man3/notify.3 b/man/man3/notify.3
index 0286ea8f..41b84521 100644
--- a/man/man3/notify.3
+++ b/man/man3/notify.3
@@ -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.
-.PP
-These default actions may be overridden.
+A note may also be posted by another process
+via
+.IR postnote (3).
+On Unix, notes are implemented as signals.
+.PP
+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.