NetBSD/share/man/man2/siginfo.2

.\"	$NetBSD: siginfo.2,v 1.4 2008/04/30 13:10:53 martin Exp $
.\"
.\" Copyright (c) 2003 The NetBSD Foundation, Inc.
.\" All rights reserved.
.\"
.\" This code is derived from software contributed to The NetBSD Foundation
.\" by Christos Zoulas.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd May 21, 2007
.Dt SIGINFO 2
.Os
.Sh NAME
.Nm siginfo
.Nd signal information
.Sh SYNOPSIS
.In signal.h
.Sh DESCRIPTION
.Nm
is a structure type which contains information about a signal delivered
to a process.
.Pp
.Nm
includes the following members:
.Bd -literal -offset indent
int si_signo;
int si_errno;
int si_code;
.Ed
.Pp
.Fa si_signo
contains the signal number generated by the system.
.Pp
If
.Fa si_errno
is non-zero, then it contains a system specific error number associated
with this signal.
This number is defined in
.Xr errno 2 .
.Pp
If
.Fa si_code
is less than or equal to zero, the signal was generated by a user process
or a user requested service:
.Bl -tag -width SI_ASYNCIO
.It SI_USER
The signal was generated via
.Xr kill 2 .
The
.Nm
structure contains the following additional members:
.Bd -literal -offset indent
pid_t si_pid;
uid_t si_uid;
.Ed
.Pp
The
.Fa si_pid
field contains the pid of the sending process and the
.Fa si_uid
field contains the user id of the sending process.
.\" .It SI_QUEUE
.\" The signal was generated via
.\" .Xr sigqueue 3 .
.\" The
.\" .Nm
.\" structure contains the following additional members:
.\" .Bd -literal -offset indent
.\" pid_t si_pid;
.\" uid_t si_uid;
.\" sigval_t si_value;
.\" .Ed
.\" .Pp
.\" The
.\" .Fa si_pid
.\" field contains the pid of the sending process and the
.\" .Fa si_uid
.\" field contains the user id of the sending process.
.\" Finally, the
.\" .Fa si_value
.\" field contains the value sent via
.\" .Xr sigqueue 3 .
.It SI_TIMER
The signal was generated because a timer set by
.Xr timer_settime 2
has expired.
The
.Nm
structure contains the following additional members:
.Bd -literal -offset indent
sigval_t si_value;
.Ed
.Pp
The
.Fa si_value
field contains the value set via
.Xr timer_create 2 .
.It SI_ASYNCIO
The signal was generated by completion of an asynchronous I/O operation.
The
.Nm
structure contains the following additional members:
.Bd -literal -offset indent
int si_fd;
long si_band;
.Ed
.Pp
The
.Fa si_fd
argument contains the file descriptor number on which the operation was
completed and the
.Fa si_band
field contains the side and priority of the operation.
If the operation was a normal read,
.Fa si_band
will contain
.Dv POLLIN | POLLRDNORM ;
on an out-of-band read it will contain
.Dv POLLPRI | POLLRDBAND ;
on a normal write it will contain
.Dv POLLOUT | POLLWRNORM ;
on an out-of-band write it will contain
.Dv POLLPRI | POLLWRBAND .
.\" .It SI_MESGQ
.\" The signal was generated because of the arrival of a message on an empty
.\" message queue.
.\" See
.\" .Xr mq_notify 3 .
.El
.Pp
If
.Fa si_code
is positive, then it contains a signal specific reason
why the signal was generated:
.Bl -tag -width SIGCHLD
.It SIGILL
.Bl -tag -width ILL_ILLOPC
.It ILL_ILLOPC
Illegal opcode
.It ILL_ILLOPN
Illegal operand
.It ILL_ILLADR
Illegal addressing mode
.It ILL_ILLTRP
Illegal trap
.It ILL_PRVOPC
Privileged opcode
.It ILL_PRVREG
Privileged register
.It ILL_COPROC
Coprocessor error
.It ILL_BADSTK
Internal stack error
.El
.It SIGFPE
.Bl -tag -width FPE_INTDIV
.It FPE_INTDIV
Integer divide by zero
.It FPE_INTOVF
Integer overflow
.It FPE_FLTDIV
Floating point divide by zero
.It FPE_FLTOVF
Floating point overflow
.It FPE_FLTUND
Floating point underflow
.It FPE_FLTRES
Floating poing inexact result
.It FPE_FLTINV
Invalid Floating poing operation
.It FPE_FLTSUB
Subscript out of range
.El
.It SIGSEGV
.Bl -tag -width SEGV_MAPERR
.It SEGV_MAPERR
Address not mapped to object
.It SEGV_ACCERR
Invalid permissions for mapped object
.El
.It SIGBUS
.Bl -tag -width BUS_ADRALN
.It BUS_ADRALN
Invalid address alignment
.It BUS_ADRERR
Non-existant physical address
.It BUS_OBJERR
Object specific hardware error
.El
.It SIGTRAP
.Bl -tag -width TRAP_BRKPT
.It TRAP_BRKPT
Process breakpoint
.It TRAP_TRACE
Process trace trap
.El
.It SIGCHLD
.Bl -tag -width CLD_CONTINUED
.It CLD_EXITED
Child has exited
.It CLD_KILLED
Child has terminated abnormally but did not create a core file
.It CLD_DUMPED
Child has terminated abnormally and created a core file
.It CLD_TRAPPED
Traced child has trapped
.It CLD_STOPPED
Child has stopped
.It CLD_CONTINUED
Stopped child has continued
.El
.It SIGPOLL
.Bl -tag -width POLL_OUT
.It POLL_IN
Data input available
.It POLL_OUT
Output buffers available
.It POLL_MSG
Input message available
.It POLL_ERR
I/O Error
.It POLL_PRI
High priority input available
.It POLL_HUP
Device disconnected
.El
.El
.Pp
For
.Dv SIGILL , SIGFPE ,
and
.Dv SIGTRAP
the
.Nm
structure contains the following additional members:
.Bd -literal -offset indent
void *si_addr;
int si_trap;
.Ed
.Pp
.Fa si_addr
contains the address of the faulting instruction and
.Fa si_trap
contains a hardware specific reason.
.Pp
For
.Dv SIGBUS
and
.Dv SIGSEGV
the
.Nm
structure contains the following additional members:
.Bd -literal -offset indent
void *si_addr;
int si_trap;
.Ed
.Pp
.Fa si_addr
contains the address of the faulting data and
.Fa si_trap
contains a hardware specific reason.
.Pp
For
.Dv SIGPOLL
the
.Nm
structure contains the following additional members:
.Bd -literal -offset indent
int si_fd;
long si_band;
.Ed
.Pp
The
.Fa si_fd
argument contains the file descriptor number on which the operation was
completed and the
.Fa si_band
field contains the side and priority of the operation as described above.
.Pp
Finally, for
.Dv SIGCHLD
the
.Nm
structure contains the following additional members:
.Bd -literal -offset indent
pid_t si_pid;
uid_t si_uid;
int si_status;
clock_t	si_utime;
clock_t	si_stime;
.Ed
.Pp
The
.Fa si_pid
field contains the pid of the process who's status changed, the
.Fa si_uid
field contains the user id of the that process, the
.Fa si_status
field contains a status code described in
.Xr waitpid 2 ,
and the
.Fa si_utime
and
.Fa si_stime
fields contain the user and system process accounting time.
.Sh STANDARDS
The
.Nm
type conforms to
.St -xsh5 .
.Sh HISTORY
The
.Nm
functionality first appeared in
.At V.4 .