notify 6.2 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244
  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. .PP
  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. .PP
  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. .PP
  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.