SIGACTION(2) Linux Programmer's Manual SIGACTION(2) NNAAMMEE sigaction, sigprocmask, sigpending, sigsuspend - POSIX signal handling functions SSYYNNOOPPSSIISS ##iinncclluuddee <> iinntt ssiiggaaccttiioonn((iinntt _s_i_g_n_u_m,, ccoonnsstt ssttrruucctt ssiiggaaccttiioonn **_a_c_t,, ssttrruucctt ssiiggaaccttiioonn **_o_l_d_a_c_t));; iinntt ssiiggpprrooccmmaasskk((iinntt _h_o_w,, ccoonnsstt ssiiggsseett__tt **_s_e_t,, ssiiggsseett__tt **_o_l_d_s_e_t));; iinntt ssiiggppeennddiinngg((ssiiggsseett__tt **_s_e_t));; iinntt ssiiggssuussppeenndd((ccoonnsstt ssiiggsseett__tt **_m_a_s_k));; DDEESSCCRRIIPPTTIIOONN The ssiiggaaccttiioonn system call is used to change the action taken by a pro- cess on receipt of a specific signal. _s_i_g_n_u_m specifies the signal and can be any valid signal except SSIIGGKKIILLLL and SSIIGGSSTTOOPP. If _a_c_t is non-null, the new action for signal _s_i_g_n_u_m is installed from _a_c_t. If _o_l_d_a_c_t is non-null, the previous action is saved in _o_l_d_a_c_t. The ssiiggaaccttiioonn structure is defined as something like struct sigaction { void (*sa_handler)(int); void (*sa_sigaction)(int, siginfo_t *, void *); sigset_t sa_mask; int sa_flags; void (*sa_restorer)(void); } On some architectures a union is involved - do not assign to both _s_a___h_a_n_d_l_e_r and _s_a___s_i_g_a_c_t_i_o_n. The _s_a___r_e_s_t_o_r_e_r element is obsolete and should not be used. POSIX does not specify a _s_a___r_e_s_t_o_r_e_r element. _s_a___h_a_n_d_l_e_r specifies the action to be associated with _s_i_g_n_u_m and may be SSIIGG__DDFFLL for the default action, SSIIGG__IIGGNN to ignore this signal, or a pointer to a signal handling function. This function receives the sig- nal number as its only argument. _s_a___s_i_g_a_c_t_i_o_n also specifies the action to be associated with _s_i_g_n_u_m. This function receives the signal number as its first argument, a pointer to a _s_i_g_i_n_f_o___t as its second argument and a pointer to a _u_c_o_n_- _t_e_x_t___t (cast to void *) as its third argument. _s_a___m_a_s_k gives a mask of signals which should be blocked during execu- tion of the signal handler. In addition, the signal which triggered the handler will be blocked, unless the SSAA__NNOODDEEFFEERR or SSAA__NNOOMMAASSKK flags are used. _s_a___f_l_a_g_s specifies a set of flags which modify the behaviour of the signal handling process. It is formed by the bitwise OR of zero or more of the following: SSAA__NNOOCCLLDDSSTTOOPP If _s_i_g_n_u_m is SSIIGGCCHHLLDD, do not receive notification when child processes stop (i.e., when child processes receive one of SSIIGGSSTTOOPP, SSIIGGTTSSTTPP, SSIIGGTTTTIINN or SSIIGGTTTTOOUU). SSAA__OONNEESSHHOOTT or SSAA__RREESSEETTHHAANNDD Restore the signal action to the default state once the signal handler has been called. SSAA__OONNSSTTAACCKK Call the signal handler on an alternate signal stack pro- vided by ssiiggaallttssttaacckk(2). If an alternate stack is not available, the default stack will be used. SSAA__RREESSTTAARRTT Provide behaviour compatible with BSD signal semantics by making certain system calls restartable across signals. SSAA__NNOOMMAASSKK or SSAA__NNOODDEEFFEERR Do not prevent the signal from being received from within its own signal handler. SSAA__SSIIGGIINNFFOO The signal handler takes 3 arguments, not one. In this case, _s_a___s_i_g_a_c_t_i_o_n should be set instead of _s_a___h_a_n_d_l_e_r. (The sa_sigaction field was added in Linux 2.1.86.) The _s_i_g_i_n_f_o___t parameter to _s_a___s_i_g_a_c_t_i_o_n is a struct with the following elements siginfo_t { int si_signo; /* Signal number */ int si_errno; /* An errno value */ int si_code; /* Signal code */ 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 */ sigval_t si_value; /* Signal value */ int si_int; /* POSIX.1b signal */ void * si_ptr; /* POSIX.1b signal */ void * si_addr; /* Memory location which caused fault */ int si_band; /* Band event */ int si_fd; /* File descriptor */ } _s_i___s_i_g_n_o, _s_i___e_r_r_n_o and _s_i___c_o_d_e are defined for all signals. The rest of the struct may be a union, so that one should only read the fields that are meaningful for the given signal. kkiillll(2), POSIX.1b signals and SIGCHLD fill in _s_i___p_i_d and _s_i___u_i_d. SIGCHLD also fills in _s_i___s_t_a_- _t_u_s, _s_i___u_t_i_m_e and _s_i___s_t_i_m_e. _s_i___i_n_t and _s_i___p_t_r are specified by the sender of the POSIX.1b signal. SIGILL, SIGFPE, SIGSEGV and SIGBUS fill in _s_i___a_d_d_r with the address of the fault. SIGPOLL fills in _s_i___b_a_n_d and _s_i___f_d. _s_i___c_o_d_e indicates why this signal was sent. It is a value, not a bit- mask. The values which are possible for any signal are listed in this table: +------------------------------------+ | _s_i___c_o_d_e | +-----------+------------------------+ |Value | Signal origin | +-----------+------------------------+ |SI_USER | kill, sigsend or raise | +-----------+------------------------+ |SI_KERNEL | The kernel | +-----------+------------------------+ |SI_QUEUE | sigqueue | +-----------+------------------------+ |SI_TIMER | timer expired | +-----------+------------------------+ |SI_MESGQ | mesq state changed | +-----------+------------------------+ |SI_ASYNCIO | AIO completed | +-----------+------------------------+ |SI_SIGIO | queued SIGIO | +-----------+------------------------+ +-------------------------------------+ | SIGILL | +-----------+-------------------------+ |ILL_ILLOPC | illegal opcode | +-----------+-------------------------+ |ILL_ILLOPN | illegal operand | +-----------+-------------------------+ |ILL_ILLADR | illegal addressing mode | +-----------+-------------------------+ |ILL_ILLTRP | illegal trap | +-----------+-------------------------+ |ILL_PRVOPC | privileged opcode | +-----------+-------------------------+ |ILL_PRVREG | privileged register | +-----------+-------------------------+ |ILL_COPROC | coprocessor error | +-----------+-------------------------+ |ILL_BADSTK | internal stack error | +-----------+-------------------------+ +----------------------------------------------+ | SIGFPE | +-----------+----------------------------------+ |FPE_INTDIV | integer divide by zero | +-----------+----------------------------------+ |FPE_INTOVF | integer overflow | +-----------+----------------------------------+ |FPE_FLTDIV | floating point divide by zero | +-----------+----------------------------------+ |FPE_FLTOVF | floating point overflow | +-----------+----------------------------------+ |FPE_FLTUND | floating point underflow | +-----------+----------------------------------+ |FPE_FLTRES | floating point inexact result | +-----------+----------------------------------+ |FPE_FLTINV | floating point invalid operation | +-----------+----------------------------------+ |FPE_FLTSUB | subscript out of range | +-----------+----------------------------------+ +----------------------------------------------------+ | SIGSEGV | +------------+---------------------------------------+ |SEGV_MAPERR | address not mapped to object | +------------+---------------------------------------+ |SEGV_ACCERR | invalid permissions for mapped object | +------------+---------------------------------------+ +--------------------------------------------+ | SIGBUS | +-----------+--------------------------------+ |BUS_ADRALN | invalid address alignment | +-----------+--------------------------------+ |BUS_ADRERR | non-existent physical address | +-----------+--------------------------------+ |BUS_OBJERR | object specific hardware error | +-----------+--------------------------------+ +--------------------------------+ | SIGTRAP | +-----------+--------------------+ |TRAP_BRKPT | process breakpoint | +-----------+--------------------+ |TRAP_TRACE | process trace trap | +-----------+--------------------+ +--------------------------------------------+ | SIGCHLD | +--------------+-----------------------------+ |CLD_EXITED | child has exited | +--------------+-----------------------------+ |CLD_KILLED | child was killed | +--------------+-----------------------------+ |CLD_DUMPED | child terminated abnormally | +--------------+-----------------------------+ |CLD_TRAPPED | traced child has trapped | +--------------+-----------------------------+ |CLD_STOPPED | child has stopped | +--------------+-----------------------------+ |CLD_CONTINUED | stopped child has continued | +--------------+-----------------------------+ +-----------------------------------------+ | SIGPOLL | +---------+-------------------------------+ |POLL_IN | data input available | +---------+-------------------------------+ |POLL_OUT | output buffers available | +---------+-------------------------------+ |POLL_MSG | input message available | +---------+-------------------------------+ |POLL_ERR | i/o error | +---------+-------------------------------+ |POLL_PRI | high priority input available | +---------+-------------------------------+ |POLL_HUP | device disconnected | +---------+-------------------------------+ The ssiiggpprrooccmmaasskk call is used to change the list of currently blocked signals. The behaviour of the call is dependent on the value of _h_o_w, as follows. SSIIGG__BBLLOOCCKK The set of blocked signals is the union of the current set and the _s_e_t argument. SSIIGG__UUNNBBLLOOCCKK The signals in _s_e_t are removed from the current set of blocked signals. It is legal to attempt to unblock a signal which is not blocked. SSIIGG__SSEETTMMAASSKK The set of blocked signals is set to the argument _s_e_t. If _o_l_d_s_e_t is non-null, the previous value of the signal mask is stored in _o_l_d_s_e_t. The ssiiggppeennddiinngg call allows the examination of pending signals (ones which have been raised while blocked). The signal mask of pending sig- nals is stored in _s_e_t. The ssiiggssuussppeenndd call temporarily replaces the signal mask for the pro- cess with that given by _m_a_s_k and then suspends the process until a sig- nal is received. RREETTUURRNN VVAALLUUEE The functions ssiiggaaccttiioonn, ssiiggpprrooccmmaasskk, and ssiiggppeennddiinngg return 0 on suc- cess and -1 on error. The function ssiiggssuussppeenndd always returns -1, nor- mally with the error EEIINNTTRR. EERRRROORRSS EEFFAAUULLTT _a_c_t, _o_l_d_a_c_t, _s_e_t, _o_l_d_s_e_t or _m_a_s_k point to memory which is not a valid part of the process address space. EEIINNTTRR System call was interrupted. EEIINNVVAALL An invalid signal was specified. This will also be generated if an attempt is made to change the action for SSIIGGKKIILLLL or SSIIGGSSTTOOPP, which cannot be caught. NNOOTTEESS It is not possible to block SSIIGGKKIILLLL or SSIIGGSSTTOOPP with the sigprocmask call. Attempts to do so will be silently ignored. According to POSIX, the behaviour of a process is undefined after it ignores a SIGFPE, SIGILL, or SIGSEGV signal that was not generated by the _k_i_l_l_(_) or the _r_a_i_s_e_(_) functions. Integer division by zero has undefined result. On some architectures it will generate a SIGFPE sig- nal. (Also dividing the most negative integer by -1 may generate SIGFPE.) Ignoring this signal might lead to an endless loop. POSIX (B.3.3.1.3) disallows setting the action for SIGCHLD to SIG_IGN. The BSD and SYSV behaviours differ, causing BSD software that sets the action for SIGCHLD to SIG_IGN to fail on Linux. The POSIX spec only defines SSAA__NNOOCCLLDDSSTTOOPP. Use of other _s_a___f_l_a_g_s is non-portable. The SSAA__RREESSEETTHHAANNDD flag is compatible with the SVr4 flag of the same name. The SSAA__NNOODDEEFFEERR flag is compatible with the SVr4 flag of the same name under kernels 1.3.9 and newer. On older kernels the Linux implementa- tion allowed the receipt of any signal, not just the one we are installing (effectively overriding any _s_a___m_a_s_k settings). The SSAA__RREESSEETTHHAANNDD and SSAA__NNOODDEEFFEERR names for SVr4 compatibility are present only in library versions 3.0.9 and greater. The SSAA__SSIIGGIINNFFOO flag is specified by POSIX.1b. Support for it was added in Linux 2.2. ssiiggaaccttiioonn can be called with a null second argument to query the cur- rent signal handler. It can also be used to check whether a given sig- nal is valid for the current machine by calling it with null second and third arguments. See ssiiggsseettooppss(3) for details on manipulating signal sets. CCOONNFFOORRMMIINNGG TTOO POSIX, SVr4. SVr4 does not document the EINTR condition. UUNNDDOOCCUUMMEENNTTEEDD Before the introduction of SSAA__SSIIGGIINNFFOO it was also possible to get some additional information, namely by using a sa_handler with second argu- ment of type _s_t_r_u_c_t _s_i_g_c_o_n_t_e_x_t. See the relevant kernel sources for details. This use is obsolete now. SSEEEE AALLSSOO kkiillll(1), kkiillll(2), kkiillllppgg(2), ppaauussee(2), ssiiggaallttssttaacckk(2), ssiiggnnaall(2), ssiiggvveecc(2), rraaiissee(3), ssiiggiinntteerrrruupptt(3), ssiiggsseettooppss(3), ssiiggnnaall(7) Linux 2.4 2001-12-29 SIGACTION(2)