From 058b0118a52061ad57694c01fc8763b22b789c4d Mon Sep 17 00:00:00 2001 From: rsc Date: Mon, 3 Jan 2005 06:40:20 +0000 Subject: Some man pages. --- man/man3/notify.3 | 213 ++++++++++++++++++++++++++---------------------------- 1 file changed, 104 insertions(+), 109 deletions(-) (limited to 'man/man3/notify.3') 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 .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. -- cgit v1.2.3