sigaction(2) System Calls Manual sigaction(2) sigaction, rt_sigaction - LIBRARY Standard C library (libc, -lc) #include int sigaction(int signum, const struct sigaction *_Nullable restrict act, struct sigaction *_Nullable restrict oldact); glibc (. feature_test_macros(7)): sigaction(): _POSIX_C_SOURCE siginfo_t: _POSIX_C_SOURCE >= 199309L sigaction() ( signal(7)). signum ; SIGKILL SIGSTOP. act NULL, signum act. oldact NULL, oldact. sigaction : struct sigaction { void (*sa_handler)(int); void (*sa_sigaction)(int, siginfo_t *, void *); sigset_t sa_mask; int sa_flags; void (*sa_restorer)(void); }; union: sa_handler sa_sigaction. sa_restorer ( POSIX sa_restorer ). sigreturn(2). sa_handler specifies the action to be associated with signum and can be one of the following: o SIG_DFL for the default action. o SIG_IGN to ignore this signal. o A pointer to a signal handling function. This function receives the signal number as its only argument. sa_flags SA_SIGINFO, sa_sigaction ( sa_handler) signum. , . sa_mask , (.. , ) . , , SA_NODEFER. flag , . : SA_NOCLDSTOP signum SIGCHLD, (.., , SIGSTOP, SIGTSTP, SIGTTIN SIGTTOU) (.., SIGCONT) (. wait(2)). SIGCHLD. SA_NOCLDWAIT ( Linux 2.6) signum SIGCHLD, . waitpid(2). SIGCHLD SIG_DFL. SA_NOCLDWAIT SIGCHLD, POSIX.1 , SIGCHLD . Linux SIGCHLD ; . SA_NODEFER Do not add the signal to the thread's signal mask while the handler is executing, unless the signal is specified in act.sa_mask. Consequently, a further instance of the signal may be delivered to the thread while it is executing the handler. This flag is meaningful only when establishing a signal handler. SA_NOMASK is an obsolete, nonstandard synonym for this flag. SA_ONSTACK , sigaltstack(2). , . . SA_RESETHAND Restore the signal action to the default upon entry to the signal handler. This flag is meaningful only when establishing a signal handler. SA_ONESHOT is an obsolete, nonstandard synonym for this flag. SA_RESTART BSD, , . . signal(7). SA_RESTORER . C , sa_restorer << " (signal trampoline). sigreturn(2). SA_SIGINFO ( Linux 2.2) , . sa_sigaction sa_handler. . SA_UNSUPPORTED ( Linux 5.11) Used to dynamically probe for flag bit support. If an attempt to register a handler succeeds with this flag set in act->sa_flags alongside other flags that are potentially unsupported by the kernel, and an immediately subsequent sigaction() call specifying the same signal number and with a non-NULL oldact argument yields SA_UNSUPPORTED clear in oldact->sa_flags, then oldact->sa_flags may be used as a bitmask describing which of the potentially unsupported flags are, in fact, supported. See the section "Dynamically probing for flag bit support" below for more details. SA_EXPOSE_TAGBITS ( Linux 5.11) Normally, when delivering a signal, an architecture-specific set of tag bits are cleared from the si_addr field of siginfo_t. If this flag is set, an architecture-specific subset of the tag bits will be preserved in si_addr. Programs that need to be compatible with Linux versions older than 5.11 must use SA_UNSUPPORTED to probe for support. siginfo_t SA_SIGINFO. act.sa_flags SA_SIGINFO, act.sa_sigaction. : void handler(int sig, siginfo_t *info, void *ucontext) { ... } : sig , . info siginfo_t -- , , . ucontext This is a pointer to a ucontext_t structure, cast to void *. The structure pointed to by this field contains signal context information that was saved on the user-space stack by the kernel; for details, see sigreturn(2). Further information about the ucontext_t structure can be found in getcontext(3) and signal(7). Commonly, the handler function doesn't make any use of the third argument. siginfo_t : siginfo_t { int si_signo; /* Signal number */ int si_errno; /* An errno value */ int si_code; /* Signal code */ int si_trapno; /* Trap number that caused hardware-generated signal (unused on most architectures) */ pid_t si_pid; /* Sending process ID */ uid_t si_uid; /* Real user ID of sending process */ int si_status; /* Exit value or signal */ clock_t si_utime; /* User time consumed */ clock_t si_stime; /* System time consumed */ union sigval si_value; /* Signal value */ int si_int; /* POSIX.1b signal */ void *si_ptr; /* POSIX.1b signal */ int si_overrun; /* Timer overrun count; POSIX.1b timers */ int si_timerid; /* Timer ID; POSIX.1b timers */ void *si_addr; /* Memory location which caused fault */ long si_band; /* Band event (was int 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) */ void *si_lower; /* Lower bound when address violation occurred (since Linux 3.19) */ void *si_upper; /* Upper bound when address violation occurred (since Linux 3.19) */ int si_pkey; /* Protection key on PTE that caused fault (since Linux 4.6) */ void *si_call_addr; /* Address of system call instruction (since Linux 3.5) */ int si_syscall; /* Number of attempted system call (since Linux 3.5) */ unsigned int si_arch; /* Architecture of attempted system call (since Linux 3.5) */ } si_signo, si_errno si_code . (si_errno Linux.) , , : o , kill(3) sigqueue(3), si_pid si_uid. , sigqueue(3), si_int si_ptr , ; sigqueue(3). o , POSIX.1b ( Linux 2.6), si_overrun si_timerid. si_timerid , ; , timer_create(2). si_overrun ; timer_getoverrun(2). Linux. o , (. SIGEV_SIGNAL mq_notify(3)), si_int/si_ptr sigev_value, mq_notify(3); si_pid -- , ; si_uid -- , . o SIGCHLD fills in si_pid, si_uid, si_status, si_utime, and si_stime, providing information about the child. The si_pid field is the process ID of the child; si_uid is the child's real user ID. The si_status field contains the exit status of the child (if si_code is CLD_EXITED), or the signal number that caused the process to change state. The si_utime and si_stime 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 getrusage(2) and times(2)). Up to Linux 2.6, and since Linux 2.6.27, these fields report CPU time in units of sysconf(_SC_CLK_TCK). In Linux 2.6 kernels before Linux 2.6.27, a bug meant that these fields reported time in units of the (configurable) system jiffy (see time(7)). o SIGILL, SIGFPE, SIGSEGV, SIGBUS SIGTRAP si_addr . si_trapno. SIGBUS, BUS_MCEERR_AO BUS_MCEERR_AR, si_addr_lsb. . , , si_addr_lsb log2(sysconf(_SC_PAGESIZE)). SIGTRAP ptrace(2) (PTRACE_EVENT_foo), si_addr , si_pid si_uid ID , . seccomp(2), . BUS_MCERR_* si_addr_lsb Linux. SEGV_BNDERR SIGSEGV si_lower si_upper. SEGV_PKUERR SIGSEGV si_pkey. o SIGIO/SIGPOLL ( Linux) si_band si_fd. si_band , , revents poll(2). si_fd , -; F_SETSIG fcntl(2). o SIGSYS, ( Linux 3.5), seccomp SECCOMP_RET_TRAP, si_call_addr, si_syscall, si_arch, si_errno , seccomp(2). si_code si_code siginfo_t, SA_SIGINFO ( ), . ptrace(2) si_code SIGTRAP ptrace : (SIGTRAP | PTRACE_EVENT_foo << 8). ptrace(2) , si_code, . glibc 2.20, ( - ) : o _XOPEN_SOURCE 500 ; o _XOPEN_SOURCE _XOPEN_SOURCE_EXTENDED; o _POSIX_C_SOURCE 200809L . TRAP_* . glibc 2.20 . , si_code , : SI_USER kill(2). SI_KERNEL SI_QUEUE sigqueue(3). SI_TIMER POSIX . SI_MESGQ ( Linux 2.6.6) POSIX; . mq_notify(3). SI_ASYNCIO AIO . SI_SIGIO Queued SIGIO (only up to Linux 2.2; from Linux 2.4 onward SIGIO/SIGPOLL fills in si_code as described below). SI_TKILL ( Linux 2.4.19) tkill(2) tgkill(2). si_code SIGILL: ILL_ILLOPC . ILL_ILLOPN . ILL_ILLADR . ILL_ILLTRP . ILL_PRVOPC . ILL_PRVREG . ILL_COPROC . ILL_BADSTK . si_code SIGFPE: FPE_INTDIV . FPE_INTOVF . FPE_FLTDIV . FPE_FLTOVF . FPE_FLTUND . FPE_FLTRES . FPE_FLTINV . FPE_FLTSUB . si_code SIGSEGV: SEGV_MAPERR . SEGV_ACCERR . SEGV_BNDERR ( Linux 3.19) . SEGV_PKUERR ( Linux 4.6) . pkeys(7). , , si_pkey. si_code SIGBUS: BUS_ADRALN . BUS_ADRERR . BUS_OBJERR , . BUS_MCEERR_AR ( Linux 2.6.32) ; BUS_MCEERR_AO ( Linux 2.6.32) , ; si_code SIGTRAP: TRAP_BRKPT . TRAP_TRACE . TRAP_BRANCH ( Linux 2.4, IA64) . TRAP_HWBKPT ( Linux 2.4, IA64) /. si_code SIGCHLD: CLD_EXITED . CLD_KILLED . CLD_DUMPED . CLD_TRAPPED . CLD_STOPPED . CLD_CONTINUED ( Linux 2.6.9) . si_code SIGIO/SIGPOLL: POLL_IN . POLL_OUT . POLL_MSG . POLL_ERR -. POLL_PRI . POLL_HUP . si_code SIGSYS: SYS_SECCOMP ( Linux 3.5) seccomp(2). Dynamically probing for flag bit support The sigaction() call on Linux accepts unknown bits set in act->sa_flags without error. The behavior of the kernel starting with Linux 5.11 is that a second sigaction() will clear unknown bits from oldact->sa_flags. However, historically, a second sigaction() call would typically leave those bits set in oldact->sa_flags. This means that support for new flags cannot be detected simply by testing for a flag in sa_flags, and a program must test that SA_UNSUPPORTED has been cleared before relying on the contents of sa_flags. Since the behavior of the signal handler cannot be guaranteed unless the check passes, it is wise to either block the affected signal while registering the handler and performing the check in this case, or where this is not possible, for example if the signal is synchronous, to issue the second sigaction() in the signal handler itself. In kernels that do not support a specific flag, the kernel's behavior is as if the flag was not set, even if the flag was set in act->sa_flags. The flags SA_NOCLDSTOP, SA_NOCLDWAIT, SA_SIGINFO, SA_ONSTACK, SA_RESTART, SA_NODEFER, SA_RESETHAND, and, if defined by the architecture, SA_RESTORER may not be reliably probed for using this mechanism, because they were introduced before Linux 5.11. However, in general, programs may assume that these flags are supported, since they have all been supported since Linux 2.6, which was released in the year 2003. See EXAMPLES below for a demonstration of the use of SA_UNSUPPORTED. sigaction() 0; -1, errno . EFAULT act oldact , . EINVAL . , SIGKILL SIGSTOP, . C glibc sigaction() (EINVAL) , NPTL. nptl(7). , (signal trampoline) C, glibc sigaction() act.sa_restorer SA_RESTORER act.sa_flags. sigreturn(2). , Linux sigaction(). , Linux 2.2, 32- sigset_t , , . rt_sigaction() sigset_t. , size_t sigsetsize, ( ) act.sa_mask oldact.sa_mask. sizeof(sigset_t) ( EINVAL). glibc sigaction() rt_sigaction(), . POSIX.1-2008. POSIX.1-2001, SVr4. POSIX.1-1990 SIGCHLD SIG_IGN. POSIX.1-2001 , SIGCHLD ( wait(2)). , BSD System V SIGCHLD , , -- SIGCHLD wait(2) . POSIX.1-1990 SA_NOCLDSTOP. POSIX.1-2001 SA_NOCLDSTOP, SA_NOCLDWAIT, SA_NODEFER, SA_ONSTACK, SA_RESETHAND, SA_RESTART SA_SIGINFO. sa_flags UNIX. SA_RESETHAND SVr4. SA_NODEFER SVr4 1.3.9 . Linux , , ( sa_mask). , fork(2), . execve(2) ; . POSIX SIGFPE, SIGILL SIGSEGV , kill(2) raise(3). . SIGFPE. (, -1 SIGFPE.) . sigaction(), NULL . , , NULL. SIGKILL SIGSTOP ( sa_mask). . sigsetops(3). , , signal-safety(7). SA_SIGINFO . sa_handler struct sigcontext, , uc_mcontext ucontext, ( ) sa_sigaction. Linux. . When delivering a signal with a SA_SIGINFO handler, the kernel does not always provide meaningful values for all of the fields of the siginfo_t that are relevant for that signal. Up to and including Linux 2.6.13, specifying SA_NODEFER in sa_flags prevents not only the delivered signal from being masked during execution of the handler, but also the signals specified in sa_mask. This bug was fixed in Linux 2.6.14. mprotect(2). Probing for flag support The following example program exits with status EXIT_SUCCESS if SA_EXPOSE_TAGBITS is determined to be supported, and EXIT_FAILURE otherwise. #include #include #include #include void handler(int signo, siginfo_t *info, void *context) { struct sigaction oldact; if (sigaction(SIGSEGV, NULL, &oldact) == -1 || (oldact.sa_flags & SA_UNSUPPORTED) || !(oldact.sa_flags & SA_EXPOSE_TAGBITS)) { _exit(EXIT_FAILURE); } _exit(EXIT_SUCCESS); } int main(void) { struct sigaction act = { 0 }; act.sa_flags = SA_SIGINFO | SA_UNSUPPORTED | SA_EXPOSE_TAGBITS; act.sa_sigaction = &handler; if (sigaction(SIGSEGV, &act, NULL) == -1) { perror("sigaction"); exit(EXIT_FAILURE); } raise(SIGSEGV); } . kill(1), kill(2), pause(2), pidfd_send_signal(2), restart_syscall(2), seccomp(2), sigaltstack(2), signal(2), signalfd(2), sigpending(2), sigprocmask(2), sigreturn(2), sigsuspend(2), wait(2), killpg(3), raise(3), siginterrupt(3), sigqueue(3), sigsetops(3), sigvec(3), core(5), signal(7) Alexander Golubev , Azamat Hackimov , Hotellook, Nikita , Spiros Georgaras , Vladislav , Yuri Kozlov ; GNU 3 , . . , , . Linux man-pages 6.06 31 2023 . sigaction(2)