Add siginfo.
This commit is contained in:
davidxu
parent
3b0631d180
commit
da6fd2f691
@ -8,6 +8,7 @@ MAN= assert.3 \
|
||||
intro.3 \
|
||||
${PTHREAD_MAN} \
|
||||
queue.3 \
|
||||
siginfo.3 \
|
||||
stdarg.3 \
|
||||
sysexits.3 \
|
||||
tgmath.3 \
|
||||
|
||||
309
share/man/man3/siginfo.3
Normal file
309
share/man/man3/siginfo.3
Normal file
@ -0,0 +1,309 @@
|
||||
.\" Copyright (c) 2005 David Xu <davidxu@FreeBSD.org>
|
||||
.\" All rights reserved.
|
||||
.\"
|
||||
.\" 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(s), this list of conditions and the following disclaimer as
|
||||
.\" the first lines of this file unmodified other than the possible
|
||||
.\" addition of one or more copyright notices.
|
||||
.\" 2. Redistributions in binary form must reproduce the above copyright
|
||||
.\" notice(s), 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 COPYRIGHT HOLDER(S) ``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 COPYRIGHT HOLDER(S) 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.
|
||||
.\"
|
||||
.\" $FreeBSD$
|
||||
.\"
|
||||
.Dd December 8, 2005
|
||||
.Dt SIGINFO 3
|
||||
.Os
|
||||
.Sh NAME
|
||||
.Nm siginfo
|
||||
.Nd "signal generation information"
|
||||
.Sh SYNOPSIS
|
||||
.In signal.h
|
||||
.Sh DESCRIPTION
|
||||
A process may request signal information when it is catching a signal.
|
||||
The information specifies why the system generated that signal.
|
||||
To request signal information in a signal handler, the user can set
|
||||
.Dv SA_SIGINFO
|
||||
in
|
||||
.Va sa_flags
|
||||
before
|
||||
.Xr sigaction 2
|
||||
is called,
|
||||
otherwise the user can use
|
||||
.Xr sigwaitinfo 2
|
||||
and
|
||||
.Xr sigtimedwait 2
|
||||
to get signal information.
|
||||
In either case, the system returns the information in a structure of type
|
||||
.Vt siginfo_t ,
|
||||
which includes the following information:
|
||||
.Bl -column ".Vt union signal" ".Va si_overrun"
|
||||
.It Sy "Type Member Description"
|
||||
.It Vt int Ta Va si_signo Ta
|
||||
signal number
|
||||
.It Vt int Ta Va si_errno Ta
|
||||
error number
|
||||
.It Vt int Ta Va si_code Ta
|
||||
signal code
|
||||
.It Vt union sigval Ta Va si_value Ta
|
||||
signal value
|
||||
.It Vt pid_t Ta Va si_pid Ta
|
||||
sending process ID
|
||||
.It Vt uid_t Ta Va si_uid Ta
|
||||
sending process's real user ID
|
||||
.It Vt void Ta Va *si_addr Ta
|
||||
address of faulting instruction
|
||||
.It Vt int Ta Va si_status Ta
|
||||
exit value or signal
|
||||
.It Vt long Ta Va si_band Ta
|
||||
band event for
|
||||
.Dv SIGPOLL
|
||||
.It Vt int Ta Va si_trapno Ta
|
||||
machine trap code
|
||||
.It Vt int Ta Va si_timerid Ta
|
||||
.Tn POSIX
|
||||
timer ID
|
||||
.It Vt int Ta Va si_overrun Ta
|
||||
.Tn POSIX
|
||||
timer overrun count
|
||||
.It Vt int Ta Va si_mqd Ta
|
||||
.Tn POSIX
|
||||
message queue ID
|
||||
.El
|
||||
.Pp
|
||||
The
|
||||
.Va si_signo
|
||||
member contains the signal number.
|
||||
.Pp
|
||||
The
|
||||
.Va si_errno
|
||||
member contains an error number defined in the file
|
||||
.In errno.h .
|
||||
.Pp
|
||||
The
|
||||
.Va si_code
|
||||
member contains a code which describes the cause of the signal.
|
||||
The macros specified in the
|
||||
.Dq Code
|
||||
column of the following table are defined
|
||||
for use as values of
|
||||
.Va si_code
|
||||
that are signal-specific or non-signal-specific reasons why the signal was
|
||||
generated:
|
||||
.Bl -column ".Dv SIGPOLL" ".Dv CLD_CONTINUED"
|
||||
.It Sy "Signal Code Reason"
|
||||
.It Dv SIGILL Ta Dv ILL_ILLOPC Ta
|
||||
illegal opcode
|
||||
.It Ta Dv ILL_ILLOPN Ta
|
||||
illegal operand
|
||||
.It Ta Dv ILL_ILLADR Ta
|
||||
illegal addressing mode
|
||||
.It Ta Dv ILL_ILLTRP Ta
|
||||
illegal trap
|
||||
.It Ta Dv ILL_PRVOPC Ta
|
||||
illegal Privileged opcode
|
||||
.It Ta Dv ILL_PRVREG Ta
|
||||
illegal Privileged register
|
||||
.It Ta Dv ILL_COPROC Ta
|
||||
coprocessor error
|
||||
.It Ta Dv ILL_BADSTK Ta
|
||||
internal stack error
|
||||
.It Dv SIGFPE Ta Dv FPE_INTDIV Ta
|
||||
integer divide by zero
|
||||
.It Ta Dv FPE_INTOVF Ta
|
||||
integer overflow
|
||||
.It Ta Dv FPE_FLTDIV Ta
|
||||
floating-point divide by zero
|
||||
.It Ta Dv FPE_FLTOVF Ta
|
||||
floating-point overflow
|
||||
.It Ta Dv FPE_FLTUND Ta
|
||||
floating-point underflow
|
||||
.It Ta Dv FPE_FLTRES Ta
|
||||
floating-point inexact result
|
||||
.It Ta Dv FPE_FLTINV Ta
|
||||
invalid floating-point operation
|
||||
.It Ta Dv FPE_FLTSUB Ta
|
||||
subscript out of range
|
||||
.It Dv SIGSEGV Ta Dv SEGV_MAPERR Ta
|
||||
address not mapped to object
|
||||
.It Ta Dv SEGV_ACCERR Ta
|
||||
invalid permissions for mapped object
|
||||
.It Dv SIGBUS Ta Dv BUS_ADRALN Ta
|
||||
invalid address alignment
|
||||
.It Ta Dv BUS_ADRERR Ta
|
||||
nonexistent physical address
|
||||
.It Ta Dv BUS_OBJERR Ta
|
||||
object-specific hardware error
|
||||
.It Dv SIGTRAP Ta Dv TRAP_BRKPT Ta
|
||||
process breakpoint
|
||||
.It Ta Dv TRAP_TRACE Ta
|
||||
process trace trap
|
||||
.It Dv SIGCHLD Ta Dv CLD_EXITED Ta
|
||||
child has exited
|
||||
.It Ta Dv CLD_KILLED Ta
|
||||
child has terminated abnormally and did not create a core file
|
||||
.It Ta Dv CLD_DUMPED Ta
|
||||
child has terminated abnormally and created a core file
|
||||
.It Ta Dv CLD_TRAPPED Ta
|
||||
traced child has trapped
|
||||
.It Ta Dv CLD_STOPPED Ta
|
||||
child has stopped
|
||||
.It Ta Dv CLD_CONTINUED Ta
|
||||
stopped child has continued
|
||||
.It Dv SIGPOLL Ta Dv POLL_IN Ta
|
||||
data input available
|
||||
.It Ta Dv POLL_OUT Ta
|
||||
output buffers available
|
||||
.It Ta Dv POLL_MSG Ta
|
||||
input message available
|
||||
.It Ta Dv POLL_ERR Ta
|
||||
I/O error
|
||||
.It Ta Dv POLL_PRI Ta
|
||||
high priority input available
|
||||
.It Ta Dv POLL_HUP Ta
|
||||
device disconnected
|
||||
.It Any Ta Dv SI_NOINFO Ta
|
||||
Only the
|
||||
.Va si_signo
|
||||
member is meaningful; the value of all other members is unspecified.
|
||||
.It Ta Dv SI_USER Ta
|
||||
signal sent by
|
||||
.Xr kill 2
|
||||
.It Ta Dv SI_QUEUE Ta
|
||||
signal sent by
|
||||
.Xr sigqueue 2
|
||||
.It Ta Dv SI_TIMER Ta
|
||||
signal generated by expiration of a timer set by
|
||||
.Xr timer_settime 2
|
||||
.It Ta Dv SI_ASYNCIO Ta
|
||||
signal generated by completion of an asynchronous I/O request
|
||||
.It Ta Dv SI_MESGQ Ta
|
||||
signal generated by arrival of a message on an empty message queue
|
||||
.El
|
||||
.Pp
|
||||
In addition, the following signal-specific information is available:
|
||||
.Bl -column ".Dv SIGPOLL" ".Dv CLD_CONTINUED"
|
||||
.It Sy "Signal Member Value"
|
||||
.It Dv SIGILL Ta Va si_addr Ta
|
||||
address of faulting instruction
|
||||
.It Ta Va si_trapno Ta
|
||||
machine dependent of trap code
|
||||
.It Dv SIGFPE Ta Va si_addr Ta
|
||||
address of faulting instruction
|
||||
.It Ta Va si_trapno Ta
|
||||
machine dependent of trap code
|
||||
.It Dv SIGSEGV Ta Va si_addr Ta
|
||||
address of faulting memory reference
|
||||
.It Ta Va si_trapno Ta
|
||||
machine dependent of trap code
|
||||
.It Dv SIGBUS Ta Va si_addr Ta
|
||||
address of faulting instruction
|
||||
.It Ta Va si_trapno Ta
|
||||
machine dependent of trap code
|
||||
.It Dv SIGCHLD Ta Vt Va si_pid Ta
|
||||
child process ID
|
||||
.It Ta Va si_status Ta
|
||||
exit value or signal
|
||||
- If
|
||||
.Va si_code
|
||||
is equal to
|
||||
.Dv CLD_EXITED ,
|
||||
then it is equal to the exit value of the child process, otherwise,
|
||||
it is equal to a signal that caused the child process to change state.
|
||||
.It Ta Va si_uid Ta "real user ID of the process that sent the signal"
|
||||
.It Dv SIGPOLL Ta Va si_band Ta "band event for"
|
||||
.Dv POLL_IN , POLL_OUT ,
|
||||
or
|
||||
.Dv POLL_MSG
|
||||
.El
|
||||
.Pp
|
||||
Finally, the following code-specific information is available:
|
||||
.Bl -column ".Dv SI_QUEUE" ".Va si_overrun"
|
||||
.It Sy "Code Member Value"
|
||||
.It Dv SI_QUEUE Ta Va si_value Ta
|
||||
the value passed to
|
||||
.Xr sigqueue 2
|
||||
system call
|
||||
.It Ta Va si_pid Ta
|
||||
the process ID that sent the signal
|
||||
.It Ta Va si_uid Ta
|
||||
real user ID of the process that sent the signal
|
||||
.It Dv SI_TIMER Ta Va si_value Ta
|
||||
the value passed to
|
||||
.Xr timer_create 2
|
||||
system call
|
||||
.It Ta Va si_timerid Ta
|
||||
the timer ID returned by
|
||||
.Xr timer_create 2
|
||||
system call
|
||||
.It Ta Va si_overrun Ta
|
||||
timer overrun count corresponding to the signal
|
||||
.It Ta Va si_errno Ta
|
||||
If timer overrun will be
|
||||
.Brq Dv DELAYTIMER_MAX ,
|
||||
an error code defined in
|
||||
.In errno.h
|
||||
is set
|
||||
.It Dv SI_ASYNCIO Ta Va si_value Ta
|
||||
the value passed to aio system calls
|
||||
.It Dv SI_MESGQ Ta Va si_value Ta
|
||||
the value passed to
|
||||
.Xr mq_notify 2
|
||||
system call
|
||||
.It Ta Va si_mqd Ta
|
||||
the ID of the message queue which generated the signal
|
||||
.El
|
||||
.Sh NOTES
|
||||
Currently, the kernel never generates
|
||||
.Dv SIGPOLL .
|
||||
Also, the
|
||||
.Xr kill 2
|
||||
system call does not queue signals, so you will not get code
|
||||
.Dv SI_USER .
|
||||
.Dv SIGCHLD
|
||||
is queued when a process changed its status or exited.
|
||||
.Tn POSIX
|
||||
Realtime Extensions like aio, timer, message queue also queue
|
||||
signals.
|
||||
For some hardware architectures, the exact value of
|
||||
.Va si_addr
|
||||
might not be available.
|
||||
.Sh SEE ALSO
|
||||
.Xr aio_read 2 ,
|
||||
.Xr kill 2 ,
|
||||
.Xr mq_notify 2 ,
|
||||
.Xr sigaction 2 ,
|
||||
.Xr sigqueue 2 ,
|
||||
.Xr sigwaitinfo 2 ,
|
||||
.Xr timer_create 2 ,
|
||||
.Xr timer_settime 2 ,
|
||||
.Xr waitpid 2
|
||||
.Sh STANDARDS
|
||||
The
|
||||
.Vt siginfo_t
|
||||
type conforms to
|
||||
.St -p1003.1-2004 .
|
||||
.Sh HISTORY
|
||||
Full support for
|
||||
.Tn POSIX
|
||||
signal information first appeared in
|
||||
.Fx 7.0 .
|
||||
.Sh AUTHORS
|
||||
This manual page was written by
|
||||
.An "David Xu" Aq davidxu@FreeBSD.org .
|
||||
Loading…
Reference in New Issue
Block a user