.\" and Copyright 2004, 2005 Michael Kerrisk <mtk.manpages@gmail.com>
.\" based on work by faith@cs.unc.edu
.\"
+.\" %%%LICENSE_START(VERBATIM)
.\" Permission is granted to make and distribute verbatim copies of this
.\" manual provided the copyright notice and this permission notice are
.\" preserved on all copies.
.\"
.\" Formatted or processed versions of this manual, if unaccompanied by
.\" the source, must acknowledge the copyright and authors of this work.
+.\" %%%LICENSE_END
.\"
.\" Modified, aeb, 960424
.\" Modified Fri Jan 31 17:31:20 1997 by Eric S. Raymond <esr@thyrsus.com>
.\" 2004-12-09, mtk, added SI_TKILL + other minor changes
.\" 2005-09-15, mtk, split sigpending(), sigprocmask(), sigsuspend()
.\" out of this page into separate pages.
+.\" 2010-06-11 Andi Kleen, add hwpoison signal extensions
+.\" 2010-06-11 mtk, improvements to discussion of various siginfo_t fields.
.\"
-.TH SIGACTION 2 2009-07-25 "Linux" "Linux Programmer's Manual"
+.TH SIGACTION 2 2013-07-30 "Linux" "Linux Programmer's Manual"
.SH NAME
sigaction \- examine and change a signal action
.SH SYNOPSIS
.ad l
.BR sigaction ():
_POSIX_C_SOURCE\ >=\ 1 || _XOPEN_SOURCE || _POSIX_SOURCE
+
+.IR siginfo_t :
+_POSIX_C_SOURCE >= 199309L
.ad b
.SH DESCRIPTION
The
as its second argument and a pointer to a
.I ucontext_t
(cast to \fIvoid\ *\fP) as its third argument.
+(Commonly, the handler function doesn't make any use of the third argument.
+See
+.BR getcontext (3)
+for further information about
+.IR ucontext_t .)
.PP
.I sa_mask
specifies a mask of signals which should be blocked
.BR SIGCHLD ,
do not receive notification when child processes stop (i.e., when they
receive one of
-.BR SIGSTOP ", " SIGTSTP ", " SIGTTIN
+.BR SIGSTOP ", " SIGTSTP ", " SIGTTIN ", "
or
.BR SIGTTOU )
or resume (i.e., they receive
.BR SIGCONT )
(see
.BR wait (2)).
-This flag is only meaningful when establishing a handler for
+This flag is meaningful only when establishing a handler for
.BR SIGCHLD .
.TP
-.BR SA_NOCLDWAIT " (Since Linux 2.6)"
+.BR SA_NOCLDWAIT " (since Linux 2.6)"
.\" To be precise: Linux 2.5.60 -- MTK
If
.I signum
do not transform children into zombies when they terminate.
See also
.BR waitpid (2).
-This flag is only meaningful when establishing a handler for
+This flag is meaningful only when establishing a handler for
.BR SIGCHLD ,
or when setting that signal's disposition to
.BR SIG_DFL .
.B SA_NODEFER
Do not prevent the signal from being received from within its own signal
handler.
-This flag is only meaningful when establishing a signal handler.
+This flag is meaningful only when establishing a signal handler.
.B SA_NOMASK
is an obsolete, nonstandard synonym for this flag.
.TP
Call the signal handler on an alternate signal stack provided by
.BR sigaltstack (2).
If an alternate stack is not available, the default stack will be used.
-This flag is only meaningful when establishing a signal handler.
+This flag is meaningful only when establishing a signal handler.
.TP
.BR SA_RESETHAND
-Restore the signal action to the default state once the signal handler
-has been called.
-This flag is only meaningful when establishing a signal handler.
+Restore the signal action to the default upon entry to the signal handler.
+This flag is meaningful only when establishing a signal handler.
.B SA_ONESHOT
is an obsolete, nonstandard synonym for this flag.
.TP
.B SA_RESTART
Provide behavior compatible with BSD signal semantics by making certain
system calls restartable across signals.
-This flag is only meaningful when establishing a signal handler.
+This flag is meaningful only when establishing a signal handler.
See
.BR signal (7)
for a discussion of system call restarting.
.TP
.BR SA_SIGINFO " (since Linux 2.2)"
-The signal handler takes 3 arguments, not one.
+The signal handler takes three arguments, not one.
In this case,
.I sa_sigaction
should be set instead of
.IR sa_handler .
-This flag is only meaningful when establishing a signal handler.
+This flag is meaningful only when establishing a signal handler.
.\" (The
.\" .I sa_sigaction
.\" field was added in Linux 2.1.86.)
int si_timerid; /* Timer ID; POSIX.1b timers */
.\" In the kernel: si_tid
void *si_addr; /* Memory location which caused fault */
- int si_band; /* Band event */
+ long si_band; /* Band event (was \fIint\fP in
+ glibc 2.3.2 and earlier) */
int si_fd; /* File descriptor */
+ short si_addr_lsb; /* Least significant bit of address
+ (since Linux 2.6.32) */
}
.fi
.in
are defined for all signals.
.RI ( si_errno
is generally unused on Linux.)
-The rest of the struct may be a union, so that one should only
-read the fields that are meaningful for the given signal:
+The rest of the struct may be a union, so that one should
+read only the fields that are meaningful for the given signal:
.IP * 2
-POSIX.1b signals and
-.B SIGCHLD
+Signals sent with
+.BR kill (2)
+and
+.BR sigqueue (3)
fill in
.IR si_pid " and " si_uid .
+In addition, signals sent with
+.BR sigqueue (3)
+fill in
+.IR si_int " and " si_ptr
+with the values specified by the sender of the signal;
+see
+.BR sigqueue (3)
+for more details.
.IP *
-POSIX.1b timers (since Linux 2.6) fill in
+Signals sent by POSIX.1b timers (since Linux 2.6) fill in
.I si_overrun
and
.IR si_timerid .
field is an internal ID used by the kernel to identify
the timer; it is not the same as the timer ID returned by
.BR timer_create (2).
+The
+.I si_overrun
+field is the timer overrun count;
+this is the same information as is obtained by a call to
+.BR timer_getoverrun (2).
+These fields are nonstandard Linux extensions.
+.IP *
+Signals sent for message queue notification (see the description of
+.B SIGEV_SIGNAL
+in
+.BR mq_notify (3))
+fill in
+.IR si_int / si_ptr ,
+with the
+.I sigev_value
+supplied to
+.BR mq_notify (3);
+.IR si_pid ,
+with the process ID of the message sender; and
+.IR si_uid ,
+with the real user ID of the message sender.
.IP *
.B SIGCHLD
fills in
-.IR si_status ", " si_utime " and " si_stime .
+.IR si_pid ", " si_uid ", " si_status ", " si_utime ", and " si_stime ,
+providing information about the child.
+The
+.I si_pid
+field is the process ID of the child;
+.I si_uid
+is the child's real user ID.
+The
+.I si_status
+field contains the exit status of the child (if
+.I si_code
+is
+.BR CLD_EXITED ),
+or the signal number that caused the process to change state.
The
.I si_utime
and
.I si_stime
-fields do not include the times used by waited-for children (unlike
+contain the user and system CPU time used by the child process;
+these fields do not include the times used by waited-for children (unlike
.BR getrusage (2)
and
.BR time (2)).
a bug meant that these fields reported time in units
of the (configurable) system jiffy (see
.BR time (7)).
-\" FIXME .
+.\" FIXME .
.\" When si_utime and si_stime where originally implemented, the
.\" measurement unit was HZ, which was the same as clock ticks
.\" (sysconf(_SC_CLK_TCK)). In 2.6, HZ became configurable, and
.\" waited-for children (as is done by getrusage() and times()
.\" and wait4()). Solaris 8 does include child times.
.IP *
-.IR si_int " and " si_ptr
-are specified by the sender of the POSIX.1b signal.
-See
-.BR sigqueue (2)
-for more details.
-.IP *
.BR SIGILL ,
.BR SIGFPE ,
.BR SIGSEGV ,
+.BR SIGBUS ,
and
-.B SIGBUS
+.BR SIGTRAP
fill in
.I si_addr
with the address of the fault.
-.B SIGPOLL
+.\" FIXME SIGTRAP also sets the following for ptrace_notify() ?
+.\" info.si_code = exit_code;
+.\" info.si_pid = task_pid_vnr(current);
+.\" info.si_uid = current_uid(); /* Real UID */
+On some architectures,
+these signals also fill in the
+.I si_trapno
+field.
+Some suberrors of
+.BR SIGBUS ,
+in particular
+.B BUS_MCEERR_AO
+and
+.BR BUS_MCEERR_AR ,
+also fill in
+.IR si_addr_lsb .
+This field indicates the least significant bit of the reported address
+and therefore the extent of the corruption.
+For example, if a full page was corrupted,
+.I si_addr_lsb
+contains
+.IR log2(sysconf(_SC_PAGESIZE)) .
+.B BUS_MCERR_*
+and
+.I si_addr_lsb
+are Linux-specific extensions.
+.IP *
+.BR SIGIO / SIGPOLL
+(the two names are synonyms on Linux)
fills in
.IR si_band " and " si_fd .
+The
+.I si_band
+event is a bit mask containing the same values as are filled in the
+.I revents
+field by
+.BR poll (2).
+The
+.I si_fd
+field indicates the file descriptor for which the I/O event occurred.
.PP
.I si_code
is a value (not a bit mask)
.TP 15
.B SI_USER
.BR kill (2)
-or
-.BR raise (3)
.TP
.B SI_KERNEL
Sent by the kernel.
.TP
.B SI_QUEUE
-.BR sigqueue (2)
+.BR sigqueue (3)
.TP
.B SI_TIMER
POSIX timer expired
AIO completed
.TP
.B SI_SIGIO
-queued SIGIO
+Queued
+.B SIGIO
+(only in kernels up to Linux 2.2; from Linux 2.4 onward
+.BR SIGIO / SIGPOLL
+fills in
+.I si_code
+as described below).
.TP
.B SI_TKILL
.BR tkill (2)
.TP
.B BUS_OBJERR
object-specific hardware error
+.TP
+.BR BUS_MCEERR_AR " (since Linux 2.6.32)"
+Hardware memory error consumed on a machine check; action required.
+.TP
+.BR BUS_MCEERR_AO " (since Linux 2.6.32)"
+Hardware memory error detected in process but not consumed; action optional.
.RE
.PP
The following values can be placed in
.TP
.B TRAP_TRACE
process trace trap
+.TP
+.BR TRAP_BRANCH " (since Linux 2.4)"
+process taken branch trap
+.TP
+.BR TRAP_HWBKPT " (since Linux 2.4)"
+hardware breakpoint/watchpoint
.RE
.PP
The following values can be placed in
The following values can be placed in
.I si_code
for a
-.B SIGPOLL
+.BR SIGIO / SIGPOLL
signal:
.RS 4
.TP 15
input message available
.TP
.B POLL_ERR
-i/o error
+I/O error
.TP
.B POLL_PRI
high priority input available
.B POLL_HUP
device disconnected
.RE
-.SH "RETURN VALUE"
+.SH RETURN VALUE
.BR sigaction ()
-returns 0 on success and \-1 on error.
+returns 0 on success; on error, \-1 is returned, and
+.I errno
+is set to indicate the error.
.SH ERRORS
.TP
.B EFAULT
is made to change the action for
.BR SIGKILL " or " SIGSTOP ", "
which cannot be caught or ignored.
-.SH "CONFORMING TO"
+.SH CONFORMING TO
POSIX.1-2001, SVr4.
.\" SVr4 does not document the EINTR condition.
.SH NOTES
.BR wait (2)
or similar.
.PP
-POSIX.1-1990 only specified
+POSIX.1-1990 specified only
.BR SA_NOCLDSTOP .
POSIX.1-2001 added
.BR SA_NOCLDWAIT ,
Use of these latter values in
.I sa_flags
may be less portable in applications intended for older
-Unix implementations.
+UNIX implementations.
.PP
The
.B SA_RESETHAND
settings).
.PP
.BR sigaction ()
-can be called with a null second argument to query the current signal
+can be called with a NULL second argument to query the current signal
handler.
It can also be used to check whether a given signal is valid for
-the current machine by calling it with null second and third arguments.
+the current machine by calling it with NULL second and third arguments.
.PP
It is not possible to block
.BR SIGKILL " or " SIGSTOP
.I sa_handler
with second argument of type
.IR "struct sigcontext".
-See the relevant kernel sources for details.
+See the relevant Linux kernel sources for details.
This use is obsolete now.
.SH BUGS
In kernels up to and including 2.6.13, specifying
.SH EXAMPLE
See
.BR mprotect (2).
-.SH "SEE ALSO"
+.SH SEE ALSO
.BR kill (1),
.BR kill (2),
.BR killpg (2),
.BR pause (2),
+.BR restart_syscall (2),
.BR sigaltstack (2),
.BR signal (2),
.BR signalfd (2),
.BR sigpending (2),
.BR sigprocmask (2),
-.BR sigqueue (2),
.BR sigsuspend (2),
.BR wait (2),
.BR raise (3),
.BR siginterrupt (3),
+.BR sigqueue (3),
.BR sigsetops (3),
.BR sigvec (3),
.BR core (5),
.BR signal (7)
+.SH COLOPHON
+This page is part of release 3.65 of the Linux
+.I man-pages
+project.
+A description of the project,
+and information about reporting bugs,
+can be found at
+\%http://www.kernel.org/doc/man\-pages/.
OSDN Git Service
