sys/man/2/notify

   1 .TH NOTIFY 2
   2 .SH NAME
   3 notify, noted, atnotify \- handle asynchronous process notification
   4 .SH SYNOPSIS
   5 .B #include <u.h>
   6 .br
   7 .B #include <libc.h>
   8 .PP
   9 .B
  10 int notify(void (*f)(void*, char*))
  11 .PP
  12 .B
  13 int noted(int v)
  14 .PP
  15 .B
  16 int atnotify(int (*f)(void*, char*), int in)
  17 .SH DESCRIPTION
  18 When a process raises an exceptional condition such as dividing by zero
  19 or writing on a closed pipe, a
  20 .I note
  21 is posted to communicate the exception.
  22 A note may also be posted by a
  23 .I write
  24 (see
  25 .IR read (2))
  26 to the process's
  27 .BI /proc/ n /note
  28 file or to the
  29 .BI /proc/ m /notepg
  30 file of a process in the same process group (see
  31 .IR proc (3)).
  32 When the note is received
  33 the behavior of the process depends on the origin of the note.
  34 If the note was posted by an external process,
  35 the process receiving the note exits;
  36 if generated by the system the note string,
  37 preceded by the name
  38 and id of the process and the string
  39 \fL"suicide: "\fP,
  40 is printed on the process's standard error file
  41 and the
  42 process is suspended in the
  43 .B Broken
  44 state for debugging.
  45 .PP
  46 These default actions may be overridden.
  47 The
  48 .I notify
  49 function registers a
  50 .I "notification handler
  51 to be called within the process when a note is received.
  52 The argument to
  53 .I notify
  54 replaces the previous handler, if any.
  55 An argument of zero cancels a previous handler,
  56 restoring the default action.
  57 A
  58 .IR fork (2)
  59 system call leaves the handler registered in
  60 both the parent and the child;
  61 .IR exec (2)
  62 restores the default behavior.
  63 Handlers may not perform floating point operations.
  64 .PP
  65 After a note is posted,
  66 the handler is called with two arguments:
  67 the first is a pointer to a
  68 .B Ureg
  69 structure (defined in
  70 .BR /$objtype/include/ureg.h )
  71 giving the current values of registers;
  72 the second is a pointer to the note itself,
  73 a null-terminated string with no more than
  74 .L ERRLEN
  75 characters in it including the terminal NUL.
  76 The
  77 .B Ureg
  78 argument is usually not needed; it is provided to help recover from traps such
  79 as floating point exceptions.
  80 Its use and layout are machine- and system-specific.
  81 .PP
  82 A notification handler must finish either by exiting the program or by calling
  83 .IR noted ;
  84 if the handler returns the behavior
  85 is undefined and probably erroneous.
  86 Until the program calls
  87 .IR noted ,
  88 any further externally-generated notes
  89 (e.g.,
  90 .B hangup
  91 or
  92 .BR alarm )
  93 will be held off, and any further notes generated by
  94 erroneous behavior by the program
  95 (such as divide by zero) will kill the program.
  96 The argument to
  97 .I noted
  98 defines the action to take:
  99 .B NDFLT
 100 instructs the system to perform the default action
 101 as if the handler had never been registered;
 102 .B NCONT
 103 instructs the system to resume the process
 104 at the point it was notified.
 105 In neither case does
 106 .I noted
 107 return to the handler.
 108 If the note interrupted an incomplete system call,
 109 that call returns an error (with error string
 110 .BR interrupted )
 111 after the process resumes.
 112 A notification handler can also jump out to an environment
 113 set up with
 114 .I setjmp
 115 using the
 116 .I notejmp
 117 function (see
 118 .IR setjmp (2)),
 119 which is implemented by modifying the saved state and calling
 120 .BR noted(NCONT) .
 121 .PP
 122 Regardless of the origin of the note or the presence of a handler,
 123 if the process is being debugged
 124 (see
 125 .IR proc (3))
 126 the arrival of a note puts the process in the
 127 .B Stopped
 128 state and awakens the debugger.
 129 .SS Atnotify
 130 Rather than using the system calls
 131 .I notify
 132 and
 133 .IR noted ,
 134 most programs should use
 135 .I atnotify
 136 to register notification handlers.
 137 The parameter
 138 .I in
 139 is non-zero to register the function
 140 .IR f ,
 141 and zero to cancel registration.
 142 A handler must return a non-zero number
 143 if the note was recognized (and resolved);
 144 otherwise it must return zero.
 145 When the system posts a note to the process,
 146 each handler registered with
 147 .I atnotify
 148 is called with arguments as
 149 described above
 150 until one of the handlers returns non-zero.
 151 Then
 152 .I noted
 153 is called with argument
 154 .BR NCONT .
 155 If no registered function returns non-zero,
 156 .I atnotify
 157 calls
 158 .I noted
 159 with argument
 160 .BR NDFLT .
 161 .SS APE
 162 .I Noted
 163 has two other possible values for its argument.
 164 .B NSAVE
 165 returns from the handler and clears the note, enabling the receipt of another,
 166 but does not return to the program.
 167 Instead it starts a new handler with the same stack, stack pointer,
 168 and arguments as the
 169 original, at the address recorded in the program counter of the
 170 .B Ureg
 171 structure.  Typically, the program counter will be overridden by the
 172 first note handler to be the address of a separate function;
 173 .B NSAVE
 174 is then a `trampoline' to that handler.
 175 That handler may executed
 176 .B noted(NRSTR)
 177 to return to the original program, usually after restoring the original program
 178 counter.
 179 .B NRSTR
 180 is identical to
 181 .BR NCONT
 182 except that it can only be executed after an
 183 .BR NSAVE .
 184 .B NSAVE
 185 and
 186 .B NRSTR
 187 are designed to improve the emulation of signals by the ANSI C/POSIX
 188 environment; their use elsewhere is discouraged.
 189 .SS Notes
 190 The set of notes a process may receive is system-dependent, but there
 191 is a common set that includes:
 192 .PP
 193 .RS 3n
 194 .nf
 195 .ta \w'\fLsys: write on closed pipe  \fP'u
 196 \fINote\fP      \fIMeaning\fP
 197 \fLinterrupt\fP user interrupt (DEL key)
 198 \fLhangup\fP    I/O connection closed
 199 \fLalarm\fP     alarm expired
 200 \fLsys: breakpoint\fP   breakpoint instruction
 201 \fLsys: bad address\fP  system call address argument out of range
 202 \fLsys: odd address\fP  system call address argument unaligned
 203 \fLsys: bad sys call\fP system call number out of range
 204 \fLsys: odd stack\fP    system call user stack unaligned
 205 \fLsys: write on closed pipe\fP write on closed pipe
 206 \fLsys: fp: \fIfptrap\f1        floating point exception
 207 \fLsys: trap: \fItrap\f1        other exception (see below)
 208 .fi
 209 .RE
 210 .PP
 211 The notes prefixed
 212 .B sys:
 213 are generated by the operating system.
 214 They are suffixed by the user program counter in format
 215 .BR pc=0x1234 .
 216 If the note is due to a floating point exception, just before the
 217 .BR pc
 218 is the address of the offending instruction in format
 219 .BR fppc=0x1234 .
 220 Notes are limited to
 221 .B ERRLEN
 222 bytes; if they would be longer they are truncated but the
 223 .B pc
 224 is always reported correctly.
 225 .PP
 226 The types and syntax of the
 227 .I trap
 228 and
 229 .I fptrap
 230 portions of the notes are machine-dependent.
 231 .SH SOURCE
 232 .B /sys/src/libc/9syscall
 233 .br
 234 .B /sys/src/libc/port/atnotify.c
 235 .SH SEE ALSO
 236 .IR intro (2),
 237 .I notejmp
 238 in
 239 .IR setjmp (2)
 240 .SH BUGS
 241 Since
 242 .IR exec (2)
 243 discards the notification handler, there is a window
 244 of vulnerability to notes in a new process.