/share/man/man3/siginfo.3

https://bitbucket.org/freebsd/freebsd-head/ · Unknown · 340 lines · 340 code · 0 blank · 0 comment · 0 complexity · 70beb10170f3c9c0e54a4f4893bff114 MD5 · raw file

  1. .\" Copyright (c) 2005 David Xu <davidxu@FreeBSD.org>
  2. .\" All rights reserved.
  3. .\"
  4. .\" Redistribution and use in source and binary forms, with or without
  5. .\" modification, are permitted provided that the following conditions
  6. .\" are met:
  7. .\" 1. Redistributions of source code must retain the above copyright
  8. .\" notice(s), this list of conditions and the following disclaimer as
  9. .\" the first lines of this file unmodified other than the possible
  10. .\" addition of one or more copyright notices.
  11. .\" 2. Redistributions in binary form must reproduce the above copyright
  12. .\" notice(s), this list of conditions and the following disclaimer in
  13. .\" the documentation and/or other materials provided with the
  14. .\" distribution.
  15. .\"
  16. .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY
  17. .\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18. .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  19. .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE
  20. .\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  21. .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  22. .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
  23. .\" BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
  24. .\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
  25. .\" OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
  26. .\" EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  27. .\"
  28. .\" $FreeBSD$
  29. .\"
  30. .Dd September 14, 2012
  31. .Dt SIGINFO 3
  32. .Os
  33. .Sh NAME
  34. .Nm siginfo
  35. .Nd "signal generation information"
  36. .Sh SYNOPSIS
  37. .In signal.h
  38. .Sh DESCRIPTION
  39. A process may request signal information when it is catching a signal.
  40. The information specifies why the system generated that signal.
  41. To request signal information in a signal handler, the user can set
  42. .Dv SA_SIGINFO
  43. in
  44. .Va sa_flags
  45. before
  46. .Xr sigaction 2
  47. is called,
  48. otherwise the user can use
  49. .Xr sigwaitinfo 2
  50. and
  51. .Xr sigtimedwait 2
  52. to get signal information.
  53. In either case, the system returns the information in a structure of type
  54. .Vt siginfo_t ,
  55. which includes the following information:
  56. .Bl -column ".Vt union signal" ".Va si_overrun"
  57. .It Sy "Type Member Description"
  58. .It Vt int Ta Va si_signo Ta
  59. signal number
  60. .It Vt int Ta Va si_errno Ta
  61. error number
  62. .It Vt int Ta Va si_code Ta
  63. signal code
  64. .It Vt union sigval Ta Va si_value Ta
  65. signal value
  66. .It Vt pid_t Ta Va si_pid Ta
  67. sending process ID
  68. .It Vt uid_t Ta Va si_uid Ta
  69. sending process's real user ID
  70. .It Vt void Ta Va *si_addr Ta
  71. address of faulting instruction
  72. .It Vt int Ta Va si_status Ta
  73. exit value or signal
  74. .It Vt long Ta Va si_band Ta
  75. band event for
  76. .Dv SIGPOLL
  77. .It Vt int Ta Va si_trapno Ta
  78. machine trap code
  79. .It Vt int Ta Va si_timerid Ta
  80. .Tn POSIX
  81. timer ID
  82. .It Vt int Ta Va si_overrun Ta
  83. .Tn POSIX
  84. timer overrun count
  85. .It Vt int Ta Va si_mqd Ta
  86. .Tn POSIX
  87. message queue ID
  88. .El
  89. .Pp
  90. The
  91. .Va si_signo
  92. member contains the signal number.
  93. .Pp
  94. The
  95. .Va si_errno
  96. member contains an error number defined in the file
  97. .In errno.h .
  98. .Pp
  99. The
  100. .Va si_code
  101. member contains a code which describes the cause of the signal.
  102. The macros specified in the
  103. .Sy Code
  104. column of the following table are defined
  105. for use as values of
  106. .Va si_code
  107. that are signal-specific or non-signal-specific reasons why the signal was
  108. generated:
  109. .Bl -column ".Dv SIGPOLL" ".Dv CLD_CONTINUED"
  110. .It Sy "Signal Code Reason"
  111. .It Dv SIGILL Ta Dv ILL_ILLOPC Ta
  112. illegal opcode
  113. .It Ta Dv ILL_ILLOPN Ta
  114. illegal operand
  115. .It Ta Dv ILL_ILLADR Ta
  116. illegal addressing mode
  117. .It Ta Dv ILL_ILLTRP Ta
  118. illegal trap
  119. .It Ta Dv ILL_PRVOPC Ta
  120. illegal privileged opcode
  121. .It Ta Dv ILL_PRVREG Ta
  122. illegal privileged register
  123. .It Ta Dv ILL_COPROC Ta
  124. coprocessor error
  125. .It Ta Dv ILL_BADSTK Ta
  126. internal stack error
  127. .It Dv SIGFPE Ta Dv FPE_INTDIV Ta
  128. integer divide by zero
  129. .It Ta Dv FPE_INTOVF Ta
  130. integer overflow
  131. .It Ta Dv FPE_FLTDIV Ta
  132. floating-point divide by zero
  133. .It Ta Dv FPE_FLTOVF Ta
  134. floating-point overflow
  135. .It Ta Dv FPE_FLTUND Ta
  136. floating-point underflow
  137. .It Ta Dv FPE_FLTRES Ta
  138. floating-point inexact result
  139. .It Ta Dv FPE_FLTINV Ta
  140. invalid floating-point operation
  141. .It Ta Dv FPE_FLTSUB Ta
  142. subscript out of range
  143. .It Dv SIGSEGV Ta Dv SEGV_MAPERR Ta
  144. address not mapped to object
  145. .It Ta Dv SEGV_ACCERR Ta
  146. invalid permissions for mapped object
  147. .It Dv SIGBUS Ta Dv BUS_ADRALN Ta
  148. invalid address alignment
  149. .It Ta Dv BUS_ADRERR Ta
  150. nonexistent physical address
  151. .It Ta Dv BUS_OBJERR Ta
  152. object-specific hardware error
  153. .It Dv SIGTRAP Ta Dv TRAP_BRKPT Ta
  154. process breakpoint
  155. .It Ta Dv TRAP_TRACE Ta
  156. process trace trap
  157. .It Ta Dv TRAP_DTRACE Ta
  158. DTrace induced trap
  159. .It Dv SIGCHLD Ta Dv CLD_EXITED Ta
  160. child has exited
  161. .It Ta Dv CLD_KILLED Ta
  162. child has terminated abnormally and did not create a core file
  163. .It Ta Dv CLD_DUMPED Ta
  164. child has terminated abnormally and created a core file
  165. .It Ta Dv CLD_TRAPPED Ta
  166. traced child has trapped
  167. .It Ta Dv CLD_STOPPED Ta
  168. child has stopped
  169. .It Ta Dv CLD_CONTINUED Ta
  170. stopped child has continued
  171. .It Dv SIGPOLL Ta Dv POLL_IN Ta
  172. data input available
  173. .It Ta Dv POLL_OUT Ta
  174. output buffers available
  175. .It Ta Dv POLL_MSG Ta
  176. input message available
  177. .It Ta Dv POLL_ERR Ta
  178. I/O error
  179. .It Ta Dv POLL_PRI Ta
  180. high priority input available
  181. .It Ta Dv POLL_HUP Ta
  182. device disconnected
  183. .It Any Ta Dv SI_NOINFO Ta
  184. Only the
  185. .Va si_signo
  186. member is meaningful; the value of all other members is unspecified.
  187. .It Ta Dv SI_USER Ta
  188. signal sent by
  189. .Xr kill 2
  190. .It Ta Dv SI_QUEUE Ta
  191. signal sent by
  192. .Xr sigqueue 2
  193. .It Ta Dv SI_TIMER Ta
  194. signal generated by expiration of a timer set by
  195. .Xr timer_settime 2
  196. .It Ta Dv SI_ASYNCIO Ta
  197. signal generated by completion of an asynchronous I/O request
  198. .It Ta Dv SI_MESGQ Ta
  199. signal generated by arrival of a message on an empty message queue
  200. .It Ta Dv SI_KERNEL Ta
  201. signal generated by miscellaneous parts of the kernel
  202. .It Ta Dv SI_LWP Ta
  203. signal sent by
  204. .Xr pthread_kill 3
  205. .El
  206. .Pp
  207. In addition, the following signal-specific information is available:
  208. .Bl -column ".Dv SIGPOLL" ".Dv CLD_CONTINUED"
  209. .It Sy "Signal Member Value"
  210. .It Dv SIGILL Ta Va si_addr Ta
  211. address of faulting instruction
  212. .It Ta Va si_trapno Ta
  213. machine dependent of trap code
  214. .It Dv SIGFPE Ta Va si_addr Ta
  215. address of faulting instruction
  216. .It Ta Va si_trapno Ta
  217. machine dependent of trap code
  218. .It Dv SIGSEGV Ta Va si_addr Ta
  219. address of faulting memory reference
  220. .It Ta Va si_trapno Ta
  221. machine dependent of trap code
  222. .It Dv SIGBUS Ta Va si_addr Ta
  223. address of faulting instruction
  224. .It Ta Va si_trapno Ta
  225. machine dependent of trap code
  226. .It Dv SIGCHLD Ta Va si_pid Ta
  227. child process ID
  228. .It Ta Va si_status Ta
  229. exit value or signal; if
  230. .Va si_code
  231. is equal to
  232. .Dv CLD_EXITED ,
  233. then it is equal to the exit value of the child process, otherwise,
  234. it is equal to a signal that caused the child process to change state.
  235. .It Ta Va si_uid Ta "real user ID of the process that sent the signal"
  236. .It Dv SIGPOLL Ta Va si_band Ta "band event for"
  237. .Dv POLL_IN , POLL_OUT ,
  238. or
  239. .Dv POLL_MSG
  240. .El
  241. .Pp
  242. Finally, the following code-specific information is available:
  243. .Bl -column ".Dv SI_QUEUE" ".Va si_overrun"
  244. .It Sy "Code Member Value"
  245. .It Dv SI_USER Ta Va si_pid Ta
  246. the process ID that sent the signal
  247. .It Ta Va si_uid Ta
  248. real user ID of the process that sent the signal
  249. .It Dv SI_QUEUE Ta Va si_value Ta
  250. the value passed to
  251. .Xr sigqueue 2
  252. system call
  253. .It Ta Va si_pid Ta
  254. the process ID that sent the signal
  255. .It Ta Va si_uid Ta
  256. real user ID of the process that sent the signal
  257. .It Dv SI_TIMER Ta Va si_value Ta
  258. the value passed to
  259. .Xr timer_create 2
  260. system call
  261. .It Ta Va si_timerid Ta
  262. the timer ID returned by
  263. .Xr timer_create 2
  264. system call
  265. .It Ta Va si_overrun Ta
  266. timer overrun count corresponding to the signal
  267. .It Ta Va si_errno Ta
  268. If timer overrun will be
  269. .Brq Dv DELAYTIMER_MAX ,
  270. an error code defined in
  271. .In errno.h
  272. is set
  273. .It Dv SI_ASYNCIO Ta Va si_value Ta
  274. the value passed to aio system calls
  275. .It Dv SI_MESGQ Ta Va si_value Ta
  276. the value passed to
  277. .Xr mq_notify 2
  278. system call
  279. .It Ta Va si_mqd Ta
  280. the ID of the message queue which generated the signal
  281. .It Dv SI_LWP Ta Va si_pid Ta
  282. the process ID that sent the signal
  283. .It Ta Va si_uid Ta
  284. real user ID of the process that sent the signal
  285. .El
  286. .Sh NOTES
  287. Currently, the kernel never generates the
  288. .Dv SIGPOLL
  289. signal.
  290. .Dv SIGCHLD
  291. signal is queued when a process changed its status or exited.
  292. .Tn POSIX
  293. Realtime Extensions like aio, timer, and message queue also queue
  294. signals.
  295. Signals with code
  296. .Dv SI_USER ,
  297. .Dv SI_KERNEL
  298. or
  299. .Dv SI_LWP
  300. are only queued if there are sufficient resources;
  301. otherwise,
  302. .Dv SI_NOINFO
  303. results.
  304. For some hardware architectures, the exact value of
  305. .Va si_addr
  306. might not be available.
  307. .Sh SEE ALSO
  308. .Xr aio_read 2 ,
  309. .Xr kill 2 ,
  310. .Xr mq_notify 2 ,
  311. .Xr sigaction 2 ,
  312. .Xr sigqueue 2 ,
  313. .Xr sigwaitinfo 2 ,
  314. .Xr timer_create 2 ,
  315. .Xr timer_settime 2 ,
  316. .Xr waitpid 2 ,
  317. .Xr pthread_kill 3
  318. .Sh STANDARDS
  319. The
  320. .Vt siginfo_t
  321. type conforms to
  322. .St -p1003.1-2004 .
  323. .Sh HISTORY
  324. Full support for
  325. .Tn POSIX
  326. signal information first appeared in
  327. .Fx 7.0 .
  328. The codes
  329. .Dv SI_USER
  330. and
  331. .Dv SI_KERNEL
  332. can be generated as of
  333. .Fx 8.1 .
  334. The code
  335. .Dv SI_LWP
  336. can be generated as of
  337. .Fx 9.0 .
  338. .Sh AUTHORS
  339. This manual page was written by
  340. .An "David Xu" Aq davidxu@FreeBSD.org .