]> git.ipfire.org Git - thirdparty/man-pages.git/blame - man2/sigaction.2
ldd.1, sprof.1, accept.2, alarm.2, bind.2, chdir.2, clock_nanosleep.2, close.2, conne...
[thirdparty/man-pages.git] / man2 / sigaction.2
CommitLineData
fea681da
MK
1'\" t
2.\" Copyright (c) 1994,1995 Mike Battersby <mib@deakin.edu.au>
c11b1abf 3.\" and Copyright 2004, 2005 Michael Kerrisk <mtk.manpages@gmail.com>
fea681da
MK
4.\" based on work by faith@cs.unc.edu
5.\"
93015253 6.\" %%%LICENSE_START(VERBATIM)
fea681da
MK
7.\" Permission is granted to make and distribute verbatim copies of this
8.\" manual provided the copyright notice and this permission notice are
9.\" preserved on all copies.
10.\"
11.\" Permission is granted to copy and distribute modified versions of this
12.\" manual under the conditions for verbatim copying, provided that the
13.\" entire resulting derived work is distributed under the terms of a
14.\" permission notice identical to this one.
c13182ef 15.\"
fea681da
MK
16.\" Since the Linux kernel and libraries are constantly changing, this
17.\" manual page may be incorrect or out-of-date. The author(s) assume no
18.\" responsibility for errors or omissions, or for damages resulting from
19.\" the use of the information contained herein. The author(s) may not
20.\" have taken the same level of care in the production of this manual,
21.\" which is licensed free of charge, as they might when working
22.\" professionally.
c13182ef 23.\"
fea681da
MK
24.\" Formatted or processed versions of this manual, if unaccompanied by
25.\" the source, must acknowledge the copyright and authors of this work.
4b72fb64 26.\" %%%LICENSE_END
fea681da
MK
27.\"
28.\" Modified, aeb, 960424
29.\" Modified Fri Jan 31 17:31:20 1997 by Eric S. Raymond <esr@thyrsus.com>
30.\" Modified Thu Nov 26 02:12:45 1998 by aeb - add SIGCHLD stuff.
1cbdceb1
MK
31.\" Modified Sat May 8 17:40:19 1999 by Matthew Wilcox
32.\" add POSIX.1b signals
33.\" Modified Sat Dec 29 01:44:52 2001 by Evan Jones <ejones@uwaterloo.ca>
34.\" SA_ONSTACK
c11b1abf 35.\" Modified 2004-11-11 by Michael Kerrisk <mtk.manpages@gmail.com>
1cbdceb1
MK
36.\" Added mention of SIGCONT under SA_NOCLDSTOP
37.\" Added SA_NOCLDWAIT
c11b1abf 38.\" Modified 2004-11-17 by Michael Kerrisk <mtk.manpages@gmail.com>
b7769f32
MK
39.\" Updated discussion for POSIX.1-2001 and SIGCHLD and sa_flags.
40.\" Formatting fixes
e1c77b39 41.\" 2004-12-09, mtk, added SI_TKILL + other minor changes
00161f1b
MK
42.\" 2005-09-15, mtk, split sigpending(), sigprocmask(), sigsuspend()
43.\" out of this page into separate pages.
665f1e69
MK
44.\" 2010-06-11 Andi Kleen, add hwpoison signal extensions
45.\" 2010-06-11 mtk, improvements to discussion of various siginfo_t fields.
3b4a59c4
KC
46.\" 2015-01-17, Kees Cook <keescook@chromium.org>
47.\" Added notes on ptrace SIGTRAP and SYS_SECCOMP.
fea681da 48.\"
460495ca 49.TH SIGACTION 2 2015-08-08 "Linux" "Linux Programmer's Manual"
fea681da 50.SH NAME
1545ed95 51sigaction, rt_sigaction \- examine and change a signal action
fea681da 52.SH SYNOPSIS
521bf584 53.nf
fea681da 54.B #include <signal.h>
c13182ef 55.sp
fea681da 56.BI "int sigaction(int " signum ", const struct sigaction *" act ,
521bf584
MK
57.BI " struct sigaction *" oldact );
58.fi
0f200f07
MK
59.sp
60.in -4n
61Feature Test Macro Requirements for glibc (see
62.BR feature_test_macros (7)):
63.in
64.sp
65.ad l
66.BR sigaction ():
67_POSIX_C_SOURCE\ >=\ 1 || _XOPEN_SOURCE || _POSIX_SOURCE
a383b70f
MK
68
69.IR siginfo_t :
70_POSIX_C_SOURCE >= 199309L
0f200f07 71.ad b
fea681da
MK
72.SH DESCRIPTION
73The
b7769f32 74.BR sigaction ()
fea681da
MK
75system call is used to change the action taken by a process on
76receipt of a specific signal.
f7d174ea
MK
77(See
78.BR signal (7)
79for an overview of signals.)
fea681da
MK
80.PP
81.I signum
82specifies the signal and can be any valid signal except
83.B SIGKILL
84and
85.BR SIGSTOP .
86.PP
87If
88.I act
f38d8f71 89is non-NULL, the new action for signal
fea681da
MK
90.I signum
91is installed from
92.IR act .
93If
94.I oldact
f38d8f71 95is non-NULL, the previous action is saved in
fea681da
MK
96.IR oldact .
97.PP
98The
b7769f32 99.I sigaction
c810983b 100structure is defined as something like:
fea681da 101.sp
bd191423 102.in +4n
fea681da
MK
103.nf
104struct sigaction {
521bf584
MK
105 void (*sa_handler)(int);
106 void (*sa_sigaction)(int, siginfo_t *, void *);
107 sigset_t sa_mask;
108 int sa_flags;
109 void (*sa_restorer)(void);
ca62583f 110};
fea681da 111.fi
bd191423 112.in
fea681da 113.PP
e9496f74 114On some architectures a union is involved: do not assign to both
fea681da
MK
115.I sa_handler
116and
117.IR sa_sigaction .
118.PP
119The
120.I sa_restorer
48c281d7
MK
121field is not intended for application use.
122(POSIX does not specify a
fea681da 123.I sa_restorer
6e57d26c 124field.)
48c281d7
MK
125Some further details of purpose of this field can be found in
126.BR sigreturn (2).
fea681da
MK
127.PP
128.I sa_handler
129specifies the action to be associated with
130.I signum
131and may be
132.B SIG_DFL
c13182ef 133for the default action,
fea681da
MK
134.B SIG_IGN
135to ignore this signal, or a pointer to a signal handling function.
136This function receives the signal number as its only argument.
137.PP
00161f1b
MK
138If
139.B SA_SIGINFO
140is specified in
c13182ef 141.IR sa_flags ,
00161f1b 142then
fea681da 143.I sa_sigaction
00161f1b
MK
144(instead of
145.IR sa_handler )
146specifies the signal-handling function for
fea681da
MK
147.IR signum .
148This function receives the signal number as its first argument, a
149pointer to a
150.I siginfo_t
151as its second argument and a pointer to a
152.I ucontext_t
c810983b 153(cast to \fIvoid\ *\fP) as its third argument.
0048657d
MK
154(Commonly, the handler function doesn't make any use of the third argument.
155See
fb872845 156.BR getcontext (3)
0048657d
MK
157for further information about
158.IR ucontext_t .)
fea681da
MK
159.PP
160.I sa_mask
7acf5ebe
MK
161specifies a mask of signals which should be blocked
162(i.e., added to the signal mask of the thread in which
163the signal handler is invoked)
164during execution of the signal handler.
c13182ef 165In addition, the signal which triggered the handler
fea681da
MK
166will be blocked, unless the
167.B SA_NODEFER
b7769f32 168flag is used.
fea681da
MK
169.PP
170.I sa_flags
bbd7e60a 171specifies a set of flags which modify the behavior of the signal.
c13182ef 172It is formed by the bitwise OR of zero or more of the following:
bd191423 173.RS 4
fea681da
MK
174.TP
175.B SA_NOCLDSTOP
176If
177.I signum
178is
1cbdceb1
MK
179.BR SIGCHLD ,
180do not receive notification when child processes stop (i.e., when they
181receive one of
12ccb8fc 182.BR SIGSTOP ", " SIGTSTP ", " SIGTTIN ", "
fea681da 183or
1cbdceb1
MK
184.BR SIGTTOU )
185or resume (i.e., they receive
186.BR SIGCONT )
187(see
188.BR wait (2)).
33a0ccb2 189This flag is meaningful only when establishing a handler for
bbd7e60a 190.BR SIGCHLD .
fea681da 191.TP
665f1e69 192.BR SA_NOCLDWAIT " (since Linux 2.6)"
1cbdceb1
MK
193.\" To be precise: Linux 2.5.60 -- MTK
194If
195.I signum
196is
197.BR SIGCHLD ,
198do not transform children into zombies when they terminate.
199See also
b7769f32 200.BR waitpid (2).
33a0ccb2 201This flag is meaningful only when establishing a handler for
bbd7e60a
MK
202.BR SIGCHLD ,
203or when setting that signal's disposition to
204.BR SIG_DFL .
205
206If the
207.B SA_NOCLDWAIT
208flag is set when establishing a handler for
209.BR SIGCHLD ,
210POSIX.1 leaves it unspecified whether a
211.B SIGCHLD
212signal is generated when a child process terminates.
213On Linux, a
214.B SIGCHLD
215signal is generated in this case;
216on some other implementations, it is not.
1cbdceb1 217.TP
c810983b
MK
218.B SA_NODEFER
219Do not prevent the signal from being received from within its own signal
220handler.
33a0ccb2 221This flag is meaningful only when establishing a signal handler.
c810983b 222.B SA_NOMASK
c8f2dd47 223is an obsolete, nonstandard synonym for this flag.
fea681da 224.TP
0daa9e92 225.B SA_ONSTACK
c13182ef 226Call the signal handler on an alternate signal stack provided by
fea681da
MK
227.BR sigaltstack (2).
228If an alternate stack is not available, the default stack will be used.
33a0ccb2 229This flag is meaningful only when establishing a signal handler.
fea681da 230.TP
c810983b 231.BR SA_RESETHAND
ca15be91 232Restore the signal action to the default upon entry to the signal handler.
33a0ccb2 233This flag is meaningful only when establishing a signal handler.
c810983b 234.B SA_ONESHOT
c8f2dd47 235is an obsolete, nonstandard synonym for this flag.
c810983b 236.TP
fea681da 237.B SA_RESTART
d9bfdb9c 238Provide behavior compatible with BSD signal semantics by making certain
fea681da 239system calls restartable across signals.
33a0ccb2 240This flag is meaningful only when establishing a signal handler.
bbd7e60a
MK
241See
242.BR signal (7)
243for a discussion of system call restarting.
fea681da 244.TP
24029e9f
MK
245.BR SA_RESTORER
246.IR "Not intended for application use" .
247This flag is used by C libraries to indicate that the
248.IR sa_restorer
249field contains the address of a "signal trampoline".
250See
251.BR sigreturn (2)
252for more details.
253.TP
bbd7e60a 254.BR SA_SIGINFO " (since Linux 2.2)"
a38a23a1 255The signal handler takes three arguments, not one.
c13182ef 256In this case,
fea681da
MK
257.I sa_sigaction
258should be set instead of
259.IR sa_handler .
33a0ccb2 260This flag is meaningful only when establishing a signal handler.
bbd7e60a
MK
261.\" (The
262.\" .I sa_sigaction
263.\" field was added in Linux 2.1.86.)
fea681da
MK
264.RE
265.PP
266The
267.I siginfo_t
c4bb193f 268argument to
fea681da 269.I sa_sigaction
a8e85174 270is a struct with the following fields:
fea681da 271.sp
bd191423 272.in +4n
fea681da 273.nf
fea681da 274siginfo_t {
bcd0ba54
MK
275 int si_signo; /* Signal number */
276 int si_errno; /* An errno value */
277 int si_code; /* Signal code */
278 int si_trapno; /* Trap number that caused
279 hardware-generated signal
280 (unused on most architectures) */
c810983b 281.\" FIXME
11c40dbd 282.\" The siginfo_t 'si_trapno' field seems to be used only on SPARC and Alpha;
c810983b 283.\" this page could use a little more detail on its purpose there.
bcd0ba54
MK
284 pid_t si_pid; /* Sending process ID */
285 uid_t si_uid; /* Real user ID of sending process */
286 int si_status; /* Exit value or signal */
287 clock_t si_utime; /* User time consumed */
288 clock_t si_stime; /* System time consumed */
289 sigval_t si_value; /* Signal value */
290 int si_int; /* POSIX.1b signal */
291 void *si_ptr; /* POSIX.1b signal */
292 int si_overrun; /* Timer overrun count;
293 POSIX.1b timers */
294 int si_timerid; /* Timer ID; POSIX.1b timers */
c810983b 295.\" In the kernel: si_tid
bcd0ba54
MK
296 void *si_addr; /* Memory location which caused fault */
297 long si_band; /* Band event (was \fIint\fP in
298 glibc 2.3.2 and earlier) */
299 int si_fd; /* File descriptor */
300 short si_addr_lsb; /* Least significant bit of address
301 (since Linux 2.6.32) */
302 void *si_call_addr; /* Address of system call instruction
303 (since Linux 3.5) */
304 int si_syscall; /* Number of attempted system call
305 (since Linux 3.5) */
306 unsigned int si_arch; /* Architecture of attempted system call
307 (since Linux 3.5) */
fea681da
MK
308}
309.fi
bd191423 310.in
fea681da
MK
311
312.IR si_signo ", " si_errno " and " si_code
313are defined for all signals.
73932e12 314.RI ( si_errno
c810983b 315is generally unused on Linux.)
33a0ccb2
MK
316The rest of the struct may be a union, so that one should
317read only the fields that are meaningful for the given signal:
2e519bf2 318.IP * 2
665f1e69
MK
319Signals sent with
320.BR kill (2)
321and
485ab701 322.BR sigqueue (3)
b7769f32 323fill in
fea681da 324.IR si_pid " and " si_uid .
4176590c 325In addition, signals sent with
485ab701 326.BR sigqueue (3)
4176590c
MK
327fill in
328.IR si_int " and " si_ptr
53d30e45 329with the values specified by the sender of the signal;
4176590c 330see
485ab701 331.BR sigqueue (3)
4176590c 332for more details.
2e519bf2 333.IP *
80752fa5 334Signals sent by POSIX.1b timers (since Linux 2.6) fill in
c810983b
MK
335.I si_overrun
336and
337.IR si_timerid .
338The
339.I si_timerid
340field is an internal ID used by the kernel to identify
341the timer; it is not the same as the timer ID returned by
804f03e6 342.BR timer_create (2).
665f1e69
MK
343The
344.I si_overrun
345field is the timer overrun count;
346this is the same information as is obtained by a call to
347.BR timer_getoverrun (2).
348These fields are nonstandard Linux extensions.
c810983b 349.IP *
5ffadafd
MK
350Signals sent for message queue notification (see the description of
351.B SIGEV_SIGNAL
352in
353.BR mq_notify (3))
354fill in
355.IR si_int / si_ptr ,
356with the
357.I sigev_value
358supplied to
359.BR mq_notify (3);
360.IR si_pid ,
361with the process ID of the message sender; and
362.IR si_uid ,
363with the real user ID of the message sender.
364.IP *
b7769f32 365.B SIGCHLD
c810983b 366fills in
a797afac 367.IR si_pid ", " si_uid ", " si_status ", " si_utime ", and " si_stime ,
665f1e69
MK
368providing information about the child.
369The
370.I si_pid
371field is the process ID of the child;
372.I si_uid
373is the child's real user ID.
374The
375.I si_status
376field contains the exit status of the child (if
377.I si_code
378is
379.BR CLD_EXITED ),
380or the signal number that caused the process to change state.
45f2d4eb
MK
381The
382.I si_utime
383and
384.I si_stime
665f1e69
MK
385contain the user and system CPU time used by the child process;
386these fields do not include the times used by waited-for children (unlike
45f2d4eb
MK
387.BR getrusage (2)
388and
7dd874ef 389.BR times (2)).
45f2d4eb
MK
390In kernels up to 2.6, and since 2.6.27, these fields report
391CPU time in units of
392.IR sysconf(_SC_CLK_TCK) .
393In 2.6 kernels before 2.6.27,
394a bug meant that these fields reported time in units
395of the (configurable) system jiffy (see
396.BR time (7)).
665f1e69 397.\" FIXME .
d03d9a05
MK
398.\" When si_utime and si_stime where originally implemented, the
399.\" measurement unit was HZ, which was the same as clock ticks
400.\" (sysconf(_SC_CLK_TCK)). In 2.6, HZ became configurable, and
401.\" was *still* used as the unit to return the info these fields,
402.\" with the result that the field values depended on the the
403.\" configured HZ. Of course, the should have been measured in
00ac6ce4 404.\" USER_HZ instead, so that sysconf(_SC_CLK_TCK) could be used to
d03d9a05
MK
405.\" convert to seconds. I have a queued patch to fix this:
406.\" http://thread.gmane.org/gmane.linux.kernel/698061/ .
45f2d4eb 407.\" This patch made it into 2.6.27.
d03d9a05 408.\" But note that these fields still don't return the times of
17b78786 409.\" waited-for children (as is done by getrusage() and times()
d03d9a05 410.\" and wait4()). Solaris 8 does include child times.
2e519bf2 411.IP *
c13182ef 412.BR SIGILL ,
b7769f32 413.BR SIGFPE ,
c13182ef 414.BR SIGSEGV ,
c2261e74 415.BR SIGBUS ,
b7769f32 416and
c2261e74 417.BR SIGTRAP
b7769f32 418fill in
fea681da
MK
419.I si_addr
420with the address of the fault.
c2261e74
MK
421On some architectures,
422these signals also fill in the
423.I si_trapno
7d082bab 424field.
f402032c 425Some suberrors of
665f1e69 426.BR SIGBUS ,
f402032c
AK
427in particular
428.B BUS_MCEERR_AO
429and
430.BR BUS_MCEERR_AR ,
431also fill in
432.IR si_addr_lsb .
433This field indicates the least significant bit of the reported address
434and therefore the extent of the corruption.
435For example, if a full page was corrupted,
436.I si_addr_lsb
b911dcb0 437contains
f402032c 438.IR log2(sysconf(_SC_PAGESIZE)) .
3b4a59c4
KC
439When
440.BR SIGTRAP
441is delivered in response to a
442.BR ptrace (2)
443event (PTRACE_EVENT_foo),
444.I si_addr
445is not populated, but
446.I si_pid
447and
448.I si_uid
449are populated with the respective process ID and user ID responsible for
e1954b03
MK
450delivering the trap.
451In the case of
c937b973 452.BR seccomp (2),
3b4a59c4 453the tracee will be shown as delivering the event.
a1d88c4c 454.B BUS_MCEERR_*
f402032c
AK
455and
456.I si_addr_lsb
457are Linux-specific extensions.
665f1e69 458.IP *
dff6bb19
MK
459.BR SIGIO / SIGPOLL
460(the two names are synonyms on Linux)
b7769f32 461fills in
fea681da 462.IR si_band " and " si_fd .
665f1e69
MK
463The
464.I si_band
465event is a bit mask containing the same values as are filled in the
466.I revents
467field by
468.BR poll (2).
469The
470.I si_fd
b1f91dc1
MK
471field indicates the file descriptor for which the I/O event occurred;
472for further details, see the description of
5ffdc2fd 473.BR F_SETSIG
b1f91dc1
MK
474in
475.BR fcntl (2).
bcd0ba54 476.IP *
a1d88c4c 477.BR SIGSYS ,
b11bccf8 478generated (since Linux 3.5)
bcd0ba54 479.\" commit a0727e8ce513fe6890416da960181ceb10fbfae6
b11bccf8
MK
480when a seccomp filter returns
481.BR SECCOMP_RET_TRAP ,
bcd0ba54
MK
482fills in
483.IR si_call_addr ,
484.IR si_syscall ,
485.IR si_arch ,
3b4a59c4
KC
486.IR si_errno ,
487and other fields as described in
bcd0ba54 488.BR seccomp (2).
2e519bf2 489.PP
fea681da 490.I si_code
e1954b03
MK
491is a value (not a bit mask) indicating why this signal was sent.
492For a
3b4a59c4
KC
493.BR ptrace (2)
494event,
495.I si_code
496will contain
497.BR SIGTRAP
498and have the ptrace event in the high byte:
499
500.nf
501 (SIGTRAP | PTRACE_EVENT_foo << 8).
502.fi
503
504For a regular signal, the following list shows the values which can be
505placed in
1812a949
MK
506.I si_code
507for any signal, along with reason that the signal was generated.
508.RS 4
d443e2fa 509.TP
1812a949 510.B SI_USER
ff953a8d 511.BR kill (2).
1812a949
MK
512.TP
513.B SI_KERNEL
514Sent by the kernel.
515.TP
516.B SI_QUEUE
ff953a8d 517.BR sigqueue (3).
1812a949
MK
518.TP
519.B SI_TIMER
ff953a8d 520POSIX timer expired.
1812a949 521.TP
eb83484f
MK
522.BR SI_MESGQ " (since Linux 2.6.6)"
523POSIX message queue state changed; see
ff953a8d 524.BR mq_notify (3).
1812a949
MK
525.TP
526.B SI_ASYNCIO
ff953a8d 527AIO completed.
1812a949
MK
528.TP
529.B SI_SIGIO
dff6bb19
MK
530Queued
531.B SIGIO
532(only in kernels up to Linux 2.2; from Linux 2.4 onward
533.BR SIGIO / SIGPOLL
534fills in
535.I si_code
536as described below).
1812a949 537.TP
eb83484f 538.BR SI_TKILL " (since Linux 2.4.19)"
1812a949
MK
539.BR tkill (2)
540or
ff953a8d 541.BR tgkill (2).
92057f4d 542.\" SI_DETHREAD is defined in 2.6.9 sources, but isn't implemented
c13182ef 543.\" It appears to have been an idea that was tried during 2.5.6
92057f4d 544.\" through to 2.5.24 and then was backed out.
1812a949
MK
545.RE
546.PP
6beb1671 547The following values can be placed in
1812a949
MK
548.I si_code
549for a
550.B SIGILL
551signal:
552.RS 4
d443e2fa 553.TP
1812a949 554.B ILL_ILLOPC
ff953a8d 555Illegal opcode.
1812a949
MK
556.TP
557.B ILL_ILLOPN
ff953a8d 558Illegal operand.
1812a949
MK
559.TP
560.B ILL_ILLADR
ff953a8d 561Illegal addressing mode.
1812a949
MK
562.TP
563.B ILL_ILLTRP
ff953a8d 564Illegal trap.
1812a949
MK
565.TP
566.B ILL_PRVOPC
ff953a8d 567Privileged opcode.
1812a949
MK
568.TP
569.B ILL_PRVREG
ff953a8d 570Privileged register.
1812a949
MK
571.TP
572.B ILL_COPROC
ff953a8d 573Coprocessor error.
1812a949
MK
574.TP
575.B ILL_BADSTK
ff953a8d 576Internal stack error.
1812a949
MK
577.RE
578.PP
6beb1671 579The following values can be placed in
1812a949
MK
580.I si_code
581for a
582.B SIGFPE
583signal:
584.RS 4
d443e2fa 585.TP
1812a949 586.B FPE_INTDIV
ff953a8d 587Integer divide by zero.
1812a949
MK
588.TP
589.B FPE_INTOVF
ff953a8d 590Integer overflow.
1812a949
MK
591.TP
592.B FPE_FLTDIV
ff953a8d 593Floating-point divide by zero.
1812a949
MK
594.TP
595.B FPE_FLTOVF
ff953a8d 596Floating-point overflow.
1812a949
MK
597.TP
598.B FPE_FLTUND
ff953a8d 599Floating-point underflow.
1812a949
MK
600.TP
601.B FPE_FLTRES
ff953a8d 602Floating-point inexact result.
1812a949
MK
603.TP
604.B FPE_FLTINV
ff953a8d 605Floating-point invalid operation.
1812a949
MK
606.TP
607.B FPE_FLTSUB
ff953a8d 608Subscript out of range.
1812a949
MK
609.RE
610.PP
6beb1671 611The following values can be placed in
1812a949
MK
612.I si_code
613for a
614.B SIGSEGV
615signal:
616.RS 4
d443e2fa 617.TP
1812a949 618.B SEGV_MAPERR
ff953a8d 619Address not mapped to object.
1812a949
MK
620.TP
621.B SEGV_ACCERR
ff953a8d 622Invalid permissions for mapped object.
1812a949
MK
623.RE
624.PP
6beb1671 625The following values can be placed in
1812a949
MK
626.I si_code
627for a
628.B SIGBUS
629signal:
630.RS 4
d443e2fa 631.TP
1812a949 632.B BUS_ADRALN
ff953a8d 633Invalid address alignment.
1812a949
MK
634.TP
635.B BUS_ADRERR
ff953a8d 636Nonexistent physical address.
1812a949
MK
637.TP
638.B BUS_OBJERR
ff953a8d 639Object-specific hardware error.
f402032c
AK
640.TP
641.BR BUS_MCEERR_AR " (since Linux 2.6.32)"
642Hardware memory error consumed on a machine check; action required.
643.TP
644.BR BUS_MCEERR_AO " (since Linux 2.6.32)"
645Hardware memory error detected in process but not consumed; action optional.
1812a949
MK
646.RE
647.PP
6beb1671 648The following values can be placed in
1812a949
MK
649.I si_code
650for a
651.B SIGTRAP
652signal:
653.RS 4
d443e2fa 654.TP
1812a949 655.B TRAP_BRKPT
ff953a8d 656Process breakpoint.
1812a949
MK
657.TP
658.B TRAP_TRACE
ff953a8d 659Process trace trap.
39efed93
MK
660.TP
661.BR TRAP_BRANCH " (since Linux 2.4)"
ff953a8d 662Process taken branch trap.
39efed93
MK
663.TP
664.BR TRAP_HWBKPT " (since Linux 2.4)"
ff953a8d 665Hardware breakpoint/watchpoint.
1812a949
MK
666.RE
667.PP
6beb1671 668The following values can be placed in
1812a949
MK
669.I si_code
670for a
688e23c6 671.B SIGCHLD
1812a949
MK
672signal:
673.RS 4
d443e2fa 674.TP
1812a949 675.B CLD_EXITED
ff953a8d 676Child has exited.
1812a949
MK
677.TP
678.B CLD_KILLED
ff953a8d 679Child was killed.
1812a949
MK
680.TP
681.B CLD_DUMPED
ff953a8d 682Child terminated abnormally.
1812a949
MK
683.TP
684.B CLD_TRAPPED
ff953a8d 685Traced child has trapped.
1812a949
MK
686.TP
687.B CLD_STOPPED
ff953a8d 688Child has stopped.
1812a949 689.TP
eb83484f 690.BR CLD_CONTINUED " (since Linux 2.6.9)"
ff953a8d 691Stopped child has continued.
1812a949
MK
692.RE
693.PP
6beb1671 694The following values can be placed in
1812a949
MK
695.I si_code
696for a
dff6bb19 697.BR SIGIO / SIGPOLL
1812a949
MK
698signal:
699.RS 4
d443e2fa 700.TP
1812a949 701.B POLL_IN
ff953a8d 702Data input available.
1812a949
MK
703.TP
704.B POLL_OUT
ff953a8d 705Output buffers available.
1812a949
MK
706.TP
707.B POLL_MSG
ff953a8d 708Input message available.
1812a949
MK
709.TP
710.B POLL_ERR
ff953a8d 711I/O error.
1812a949
MK
712.TP
713.B POLL_PRI
ff953a8d 714High priority input available.
1812a949
MK
715.TP
716.B POLL_HUP
ff953a8d 717Device disconnected.
1812a949 718.RE
3b4a59c4
KC
719.PP
720The following value can be placed in
721.I si_code
722for a
723.BR SIGSYS
724signal:
725.RS 4
d443e2fa 726.TP
3b4a59c4 727.BR SYS_SECCOMP " (since Linux 3.5)"
ff953a8d 728Triggered by a
3b4a59c4 729.BR seccomp (2)
ff953a8d 730filter rule.
3b4a59c4 731.RE
47297adb 732.SH RETURN VALUE
00161f1b 733.BR sigaction ()
de86e93c
MK
734returns 0 on success; on error, \-1 is returned, and
735.I errno
736is set to indicate the error.
fea681da
MK
737.SH ERRORS
738.TP
739.B EFAULT
00161f1b
MK
740.IR act " or " oldact
741points to memory which is not a valid part of the process address space.
fea681da
MK
742.TP
743.B EINVAL
c13182ef
MK
744An invalid signal was specified.
745This will also be generated if an attempt
fea681da
MK
746is made to change the action for
747.BR SIGKILL " or " SIGSTOP ", "
00161f1b 748which cannot be caught or ignored.
47297adb 749.SH CONFORMING TO
ab8cd127 750POSIX.1-2001, POSIX.1-2008, SVr4.
2dd578fd 751.\" SVr4 does not document the EINTR condition.
fea681da 752.SH NOTES
3fb46b2b 753A child created via
0ac0def4
MK
754.BR fork (2)
755inherits a copy of its parent's signal dispositions.
756During an
757.BR execve (2),
758the dispositions of handled signals are reset to the default;
759the dispositions of ignored signals are left unchanged.
760
d9bfdb9c 761According to POSIX, the behavior of a process is undefined after it
b7769f32
MK
762ignores a
763.BR SIGFPE ,
764.BR SIGILL ,
765or
0daa9e92 766.B SIGSEGV
b7769f32 767signal that was not generated by
0bfa087b 768.BR kill (2)
b7769f32 769or
0bfa087b 770.BR raise (3).
fea681da 771Integer division by zero has undefined result.
b7769f32
MK
772On some architectures it will generate a
773.B SIGFPE
774signal.
8bd58774
MK
775(Also dividing the most negative integer by \-1 may generate
776.BR SIGFPE .)
fea681da
MK
777Ignoring this signal might lead to an endless loop.
778.PP
b7769f32
MK
779POSIX.1-1990 disallowed setting the action for
780.B SIGCHLD
781to
782.BR SIG_IGN .
ab8cd127 783POSIX.1-2001 and later allow this possibility, so that ignoring
b7769f32
MK
784.B SIGCHLD
785can be used to prevent the creation of zombies (see
786.BR wait (2)).
efbfd7ec 787Nevertheless, the historical BSD and System\ V behaviors for ignoring
b7769f32
MK
788.B SIGCHLD
789differ, so that the only completely portable method of ensuring that
790terminated children do not become zombies is to catch the
791.B SIGCHLD
792signal and perform a
793.BR wait (2)
794or similar.
fea681da 795.PP
33a0ccb2 796POSIX.1-1990 specified only
fea681da 797.BR SA_NOCLDSTOP .
b7769f32 798POSIX.1-2001 added
e6a773f6 799.BR SA_NOCLDSTOP ,
b7769f32 800.BR SA_NOCLDWAIT ,
b7769f32 801.BR SA_NODEFER ,
e6a773f6
MK
802.BR SA_ONSTACK ,
803.BR SA_RESETHAND ,
804.BR SA_RESTART ,
b7769f32
MK
805and
806.BR SA_SIGINFO .
807Use of these latter values in
fea681da 808.I sa_flags
b7769f32 809may be less portable in applications intended for older
008f1ecc 810UNIX implementations.
b7769f32 811.PP
fea681da
MK
812The
813.B SA_RESETHAND
814flag is compatible with the SVr4 flag of the same name.
815.PP
816The
817.B SA_NODEFER
818flag is compatible with the SVr4 flag of the same name under kernels
c13182ef
MK
8191.3.9 and newer.
820On older kernels the Linux implementation
fea681da
MK
821allowed the receipt of any signal, not just the one we are installing
822(effectively overriding any
823.I sa_mask
824settings).
fea681da 825.PP
b7769f32 826.BR sigaction ()
460b3d61 827can be called with a NULL second argument to query the current signal
c13182ef
MK
828handler.
829It can also be used to check whether a given signal is valid for
460b3d61 830the current machine by calling it with NULL second and third arguments.
fea681da 831.PP
c13182ef 832It is not possible to block
00161f1b
MK
833.BR SIGKILL " or " SIGSTOP
834(by specifying them in
835.IR sa_mask ).
836Attempts to do so are silently ignored.
837.PP
fea681da
MK
838See
839.BR sigsetops (3)
840for details on manipulating signal sets.
2e519bf2
MK
841.PP
842See
843.BR signal (7)
988db661 844for a list of the async-signal-safe functions that can be
2e519bf2 845safely called inside from inside a signal handler.
1545ed95 846.\"
0722a578 847.SS C library/kernel differences
ee053db8
MK
848The glibc wrapper function for
849.BR sigaction ()
850gives an error
851.RB ( EINVAL )
852on attempts to change the disposition of the two real-time signals
853used internally by the NPTL threading implementation.
854See
855.BR nptl (7)
856for details.
857
1545ed95
MK
858The original Linux system call was named
859.BR sigaction ().
860However, with the addition of real-time signals in Linux 2.2,
861the fixed-size, 32-bit
862.IR sigset_t
863type supported by that system call was no longer fit for purpose.
864Consequently, a new system call,
865.BR rt_sigaction (),
866was added to support an enlarged
867.IR sigset_t
868type.
869The new system call takes a fourth argument,
870.IR "size_t sigsetsize" ,
871which specifies the size in bytes of the signal sets in
872.IR act.sa_mask
873and
874.IR oldact.sa_mask .
875This argument is currently required to have the value
876.IR sizeof(sigset_t)
877(or the error
878.B EINVAL
879results).
880The glibc
881.BR sigaction ()
882wrapper function hides these details from us, transparently calling
883.BR rt_sigaction ()
884when the kernel provides it.
885.\"
4a19cb8c
MK
886.SS Undocumented
887Before the introduction of
d231b918 888.BR SA_SIGINFO ,
4a19cb8c
MK
889it was also possible to get some additional information,
890namely by using a
891.I sa_handler
892with second argument of type
893.IR "struct sigcontext".
66a9882e 894See the relevant Linux kernel sources for details.
4a19cb8c 895This use is obsolete now.
00161f1b
MK
896.SH BUGS
897In kernels up to and including 2.6.13, specifying
898.B SA_NODEFER
899in
900.I sa_flags
437a9182 901prevents not only the delivered signal from being masked during
00161f1b
MK
902execution of the handler, but also the signals specified in
903.IR sa_mask .
0643ee28 904This bug was fixed in kernel 2.6.14.
af5267b2
MK
905.SH EXAMPLE
906See
907.BR mprotect (2).
47297adb 908.SH SEE ALSO
fea681da
MK
909.BR kill (1),
910.BR kill (2),
292d25b0 911.BR killpg (2),
fea681da 912.BR pause (2),
d806bc05 913.BR restart_syscall (2),
3b4a59c4 914.BR seccomp (2)
fea681da
MK
915.BR sigaltstack (2),
916.BR signal (2),
058c1165 917.BR signalfd (2),
00161f1b 918.BR sigpending (2),
b71aac7e 919.BR sigreturn (2),
00161f1b 920.BR sigprocmask (2),
00161f1b 921.BR sigsuspend (2),
b7769f32 922.BR wait (2),
fea681da
MK
923.BR raise (3),
924.BR siginterrupt (3),
485ab701 925.BR sigqueue (3),
fea681da 926.BR sigsetops (3),
30ecea55 927.BR sigvec (3),
e1a9bc1b 928.BR core (5),
fea681da 929.BR signal (7)