xref: /netbsd-src/share/man/man2/siginfo.2 (revision e89934bbf778a6d6d6894877c4da59d0c7835b0f) 
1.\"	$NetBSD: siginfo.2,v 1.21 2017/01/14 06:55:40 kamil Exp $
2.\"
3.\" Copyright (c) 2003 The NetBSD Foundation, Inc.
4.\" All rights reserved.
5.\"
6.\" This code is derived from software contributed to The NetBSD Foundation
7.\" by Christos Zoulas.
8.\"
9.\" Redistribution and use in source and binary forms, with or without
10.\" modification, are permitted provided that the following conditions
11.\" are met:
12.\" 1. Redistributions of source code must retain the above copyright
13.\"    notice, this list of conditions and the following disclaimer.
14.\" 2. Redistributions in binary form must reproduce the above copyright
15.\"    notice, this list of conditions and the following disclaimer in the
16.\"    documentation and/or other materials provided with the distribution.
17.\"
18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
21.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
28.\" POSSIBILITY OF SUCH DAMAGE.
29.\"
30.Dd January 14, 2017
31.Dt SIGINFO 2
32.Os
33.Sh NAME
34.Nm siginfo
35.Nd signal information
36.Sh SYNOPSIS
37.In signal.h
38.Sh DESCRIPTION
39.Nm
40is a structure type which contains information about a signal delivered
41to a process.
42.Pp
43.Nm
44includes the following members:
45.Bd -literal -offset indent
46int si_signo;
47int si_errno;
48int si_code;
49.Ed
50.Pp
51.Fa si_signo
52contains the signal number generated by the system.
53.Pp
54If
55.Fa si_errno
56is non-zero, then it contains a system specific error number associated
57with this signal.
58This number is defined in
59.Xr errno 2 .
60.Pp
61If
62.Fa si_code
63is less than or equal to zero, the signal was generated by a user process
64or a user requested service:
65.Bl -tag -width SI_ASYNCIO
66.It SI_USER
67The signal was generated via
68.Xr kill 2 .
69The
70.Nm
71structure contains the following additional members:
72.Bd -literal -offset indent
73pid_t si_pid;
74uid_t si_uid;
75.Ed
76.Pp
77The
78.Fa si_pid
79field contains the pid of the sending process and the
80.Fa si_uid
81field contains the user id of the sending process.
82.It SI_QUEUE
83The signal was generated via
84.Xr sigqueue 2 .
85The
86.Nm
87structure contains the following additional members:
88.Bd -literal -offset indent
89pid_t si_pid;
90uid_t si_uid;
91sigval_t si_value;
92.Ed
93.Pp
94The
95.Fa si_pid
96field contains the pid of the sending process and the
97.Fa si_uid
98field contains the user id of the sending process.
99Finally, the
100.Fa si_value
101field contains the value sent via
102.Xr sigqueue 2 .
103.It SI_TIMER
104The signal was generated because a timer set by
105.Xr timer_settime 2
106has expired.
107The
108.Nm
109structure contains the following additional members:
110.Bd -literal -offset indent
111sigval_t si_value;
112.Ed
113.Pp
114The
115.Fa si_value
116field contains the value set via
117.Xr timer_create 2 .
118.It SI_ASYNCIO
119The signal was generated by completion of an asynchronous I/O operation.
120The
121.Nm
122structure contains the following additional members:
123.Bd -literal -offset indent
124int si_fd;
125long si_band;
126.Ed
127.Pp
128The
129.Fa si_fd
130argument contains the file descriptor number on which the operation was
131completed and the
132.Fa si_band
133field contains the side and priority of the operation.
134If the operation was a normal read,
135.Fa si_band
136will contain
137.Dv POLLIN | POLLRDNORM ;
138on an out-of-band read it will contain
139.Dv POLLPRI | POLLRDBAND ;
140on a normal write it will contain
141.Dv POLLOUT | POLLWRNORM ;
142on an out-of-band write it will contain
143.Dv POLLPRI | POLLWRBAND .
144.It SI_MESGQ
145The signal was generated because of the arrival of a message on an empty
146message queue.
147See
148.Xr mq_notify 3 .
149.It SI_LWP
150The signal was generated via
151.Xr _lwp_kill 2 .
152The
153.Nm
154structure contains the following additional members:
155.Bd -literal -offset indent
156pid_t si_pid;
157uid_t si_uid;
158.Ed
159.Pp
160The
161.Fa si_pid
162field contains the pid of the sending process and the
163.Fa si_uid
164field contains the user id of the sending process.
165.It SI_NOINFO
166The signal was generated without specific info available.
167.El
168.Pp
169If
170.Fa si_code
171is positive, then it contains a signal specific reason
172why the signal was generated:
173.Bl -tag -width SIGCHLD
174.It SIGILL
175.Bl -tag -width ILL_ILLOPC
176.It ILL_BADSTK
177Internal stack error
178.It ILL_COPROC
179Coprocessor error
180.It ILL_ILLADR
181Illegal addressing mode
182.It ILL_ILLOPC
183Illegal opcode
184.It ILL_ILLOPN
185Illegal operand
186.It ILL_ILLTRP
187Illegal trap
188.It ILL_PRVOPC
189Privileged opcode
190.It ILL_PRVREG
191Privileged register
192.El
193.It SIGFPE
194.Bl -tag -width FPE_INTDIV
195.It FPE_FLTDIV
196Floating-point divide by zero
197.It FPE_FLTINV
198Invalid floating-point operation
199.It FPE_FLTOVF
200Floating-point overflow
201.It FPE_FLTRES
202Floating-point inexact result
203.It FPE_FLTUND
204Floating-point underflow
205.It FPE_FLTSUB
206Subscript out of range
207.It FPE_INTDIV
208Integer divide by zero
209.It FPE_INTOVF
210Integer overflow
211.El
212.It SIGSEGV
213.Bl -tag -width SEGV_MAPERR
214.It SEGV_ACCERR
215Invalid permissions for mapped object
216.It SEGV_MAPERR
217Address not mapped to object
218.El
219.It SIGBUS
220.Bl -tag -width BUS_ADRALN
221.It BUS_ADRALN
222Invalid address alignment
223.It BUS_ADRERR
224Nonexistent physical address
225.It BUS_OBJERR
226Object-specific hardware error
227.El
228.It SIGTRAP
229.Bl -tag -width TRAP_BRKPT
230.It TRAP_BRKPT
231Process breakpoint
232.It TRAP_CHLD
233Process child trap
234.It TRAP_EXEC
235Process exec trap
236.It TRAP_LWP
237Process LWP trap
238.It TRAP_TRACE
239Process trace trap
240.El
241.It SIGCHLD
242.Bl -tag -width CLD_CONTINUED
243.It CLD_CONTINUED
244Stopped child has continued
245.It CLD_DUMPED
246Child has terminated abnormally and created a core file
247.It CLD_EXITED
248Child has exited
249.It CLD_KILLED
250Child has terminated abnormally but did not create a core file
251.It CLD_STOPPED
252Child has stopped
253.It CLD_TRAPPED
254Traced child has trapped
255.El
256.It SIGIO
257.Bl -tag -width POLL_OUT
258.It POLL_ERR
259I/O error
260.It POLL_HUP
261Device disconnected
262.It POLL_IN
263Data input available
264.It POLL_MSG
265Input message available
266.It POLL_OUT
267Output buffers available
268.It POLL_PRI
269High priority input available
270.El
271.El
272.Pp
273For
274.Dv SIGILL , SIGFPE ,
275and
276.Dv SIGTRAP
277the
278.Nm
279structure contains the following additional members:
280.Bd -literal -offset indent
281void *si_addr;
282int si_trap;
283.Ed
284.Pp
285.Fa si_addr
286contains the address of the faulting instruction and
287.Fa si_trap
288contains a hardware specific reason.
289.Pp
290For
291.Dv SIGBUS
292and
293.Dv SIGSEGV
294the
295.Nm
296structure contains the following additional members:
297.Bd -literal -offset indent
298void *si_addr;
299int si_trap;
300.Ed
301.Pp
302.Fa si_addr
303contains the address of the faulting data and
304.Fa si_trap
305contains a hardware specific reason.
306.Pp
307For some architectures
308the value of
309.Fa si_addr
310may be inaccurate.
311.Pp
312For
313.Dv SIGIO
314the
315.Nm
316structure contains the following additional members:
317.Bd -literal -offset indent
318int si_fd;
319long si_band;
320.Ed
321.Pp
322The
323.Fa si_fd
324argument contains the file descriptor number on which the operation was
325completed and the
326.Fa si_band
327field contains the side and priority of the operation as described above.
328.Pp
329Finally, for
330.Dv SIGCHLD
331the
332.Nm
333structure contains the following additional members:
334.Bd -literal -offset indent
335pid_t si_pid;
336uid_t si_uid;
337int si_status;
338clock_t	si_utime;
339clock_t	si_stime;
340.Ed
341.Pp
342The
343.Fa si_pid
344field contains the pid of the process who's status changed, the
345.Fa si_uid
346field contains the user id of the that process, the
347.Fa si_status
348field contains either the exit code of the process (for
349.Dv CLD_EXITED ) ,
350or the signal number received by the process.
351.Xr waitid 2 ,
352.Xr waitpid 2 ,
353and the
354.Fa si_utime
355and
356.Fa si_stime
357fields contain the user and system process accounting time.
358.Sh STANDARDS
359The
360.Nm
361type conforms to
362.St -xsh5 .
363.Pp
364Signals specifying
365.Dv SI_LWP
366or
367.Dv SI_NOINFO
368are
369.Nx
370extensions.
371.Pp
372The
373.Dv TRAP_EXEC
374signal specific reason of
375.Dv SIGTRAP
376is
377.Nx
378extension.
379.Sh HISTORY
380The
381.Nm
382functionality first appeared in
383.At V.4 .
384.Pp
385.Dv TRAP_CHLD
386and
387.Dv TRAP_EXEC
388first appeared
389in
390.Nx 8 .
391