1SIGACTION(2) 386BSD Programmer's Manual SIGACTION(2) 2 3NNAAMMEE 4 ssiiggaaccttiioonn - software signal facilities 5 6SSYYNNOOPPSSIISS 7 ##iinncclluuddee <<ssiiggnnaall..hh>> 8 struct sigaction { 9 void (*sa_handler)(); 10 sigset_t sa_mask; 11 int sa_flags; 12 }; 13 14 ssiiggaaccttiioonn(_i_n_t _s_i_g, _s_t_r_u_c_t _s_i_g_a_c_t_i_o_n *_a_c_t, _s_t_r_u_c_t _s_i_g_a_c_t_i_o_n *_o_a_c_t) 15 16DDEESSCCRRIIPPTTIIOONN 17 The system defines a set of signals that may be delivered to a process. 18 Signal delivery resembles the occurence of a hardware interrupt: the 19 signal is blocked from further occurrence, the current process context is 20 saved, and a new one is built. A process may specify a _h_a_n_d_l_e_r to which 21 a signal is delivered, or specify that a signal is to be _i_g_n_o_r_e_d. A 22 process may also specify that a default action is to be taken by the 23 system when a signal occurs. A signal may also be _b_l_o_c_k_e_d, in which case 24 its delivery is postponed until it is _u_n_b_l_o_c_k_e_d. The action to be taken 25 on delivery is determined at the time of delivery. Normally, signal 26 handlers execute on the current stack of the process. This may be 27 changed, on a per-handler basis, so that signals are taken on a special 28 _s_i_g_n_a_l _s_t_a_c_k. 29 30 Signal routines execute with the signal that caused their invocation 31 _b_l_o_c_k_e_d, but other signals may yet occur. A global _s_i_g_n_a_l _m_a_s_k defines 32 the set of signals currently blocked from delivery to a process. The 33 signal mask for a process is initialized from that of its parent 34 (normally empty). It may be changed with a sigprocmask(2) call, or when 35 a signal is delivered to the process. 36 37 When a signal condition arises for a process, the signal is added to a 38 set of signals pending for the process. If the signal is not currently 39 _b_l_o_c_k_e_d by the process then it is delivered to the process. Signals may 40 be delivered any time a process enters the operating system (e.g., during 41 a system call, page fault or trap, or clock interrupt). If multiple 42 signals are ready to be delivered at the same time, any signals that 43 could be caused by traps are delivered first. Additional signals may be 44 processed at the same time, with each appearing to interrupt the handlers 45 for the previous signals before their first instructions. The set of 46 pending signals is returned by the sigpending(2) function. When a caught 47 signal is delivered, the current state of the process is saved, a new 48 signal mask is calculated (as described below), and the signal handler is 49 invoked. The call to the handler is arranged so that if the signal 50 handling routine returns normally the process will resume execution in 51 the context from before the signal's delivery. If the process wishes to 52 resume in a different context, then it must arrange to restore the 53 previous context itself. 54 55 When a signal is delivered to a process a new signal mask is installed 56 for the duration of the process' signal handler (or until a sigprocmask 57 call is made). This mask is formed by taking the union of the current 58 signal mask set, the signal to be delivered, and the signal mask 59 associated with the handler to be invoked. 60 61 SSiiggaaccttiioonn() assigns an action for a specific signal. If _a_c_t is non-zero, 62 it specifies an action (SIG_DFL, SIG_IGN, or a handler routine) and mask 63 to be used when delivering the specified signal. If _o_a_c_t is non-zero, 64 the previous handling information for the signal is returned to the user. 65 66 67 Once a signal handler is installed, it remains installed until another 68 ssiiggaaccttiioonn() call is made, or an execve(2) is performed. A signal- 69 specific default action may be reset by setting _s_a__h_a_n_d_l_e_r to SIG_DFL. 70 The defaults are process termination, possibly with core dump; no action; 71 stopping the process; or continuing the process. See the signal list 72 below for each signal's default action. If _s_a__h_a_n_d_l_e_r is SIG_IGN current 73 and pending instances of the signal are ignored and discarded. 74 75 Options may be specified by setting _s_a__f_l_a_g_s. If the SA_NOCLDSTOP bit is 76 set when installing a catching function for the SIGCHLD signal, the 77 SIGCHLD signal will be generated only when a child process exits, not 78 when a child process stops. Further, if the SA_ONSTACK bit is set in 79 _s_a__f_l_a_g_s, the system will deliver the signal to the process on a _s_i_g_n_a_l 80 _s_t_a_c_k, specified with sigstack(2). 81 82 If a signal is caught during the system calls listed below, the call may 83 be forced to terminate with the error EINTR, or the call may be 84 restarted. Restart of pending calls is requested by setting the 85 SA_RESTART bit in _s_a__f_l_a_g_s. The affected system calls include read(2), 86 write(2), sendto(2), recvfrom(2), sendmsg(2) and recvmsg(2) on a 87 communications channel or a slow device (such as a terminal, but not a 88 regular file) and during a wait(2) or ioctl(2). However, calls that have 89 already committed are not restarted, but instead return a partial success 90 (for example, a short read count). 91 92 After a fork(2) or vfork(2) all signals, the signal mask, the signal 93 stack, and the restart/interrupt flags are inherited by the child. 94 95 Execve(2) reinstates the default action for all signals which were caught 96 and resets all signals to be caught on the user stack. Ignored signals 97 remain ignored; the signal mask remains the same; signals that restart 98 pending system calls continue to do so. 99 100 The following is a list of all signals with names as in the include file 101 <_s_i_g_n_a_l._h>: 102 103 NNAAMMEE DDeeffaauulltt AAccttiioonn DDeessccrriippttiioonn 104 SIGHUP terminate process terminal line hangup 105 SIGINT terminate process interrupt program 106 SIGQUIT create core image quit program 107 SIGILL create core image illegal instruction 108 SIGTRAP create core image trace trap 109 SIGABRT create core image abort(2) call (formerly SIGIOT) 110 SIGEMT create core image emulate instruction executed 111 SIGFPE create core image floating-point exception 112 SIGKILL terminate process kill program 113 SIGBUS create core image bus error 114 SIGSEGV create core image segmentation violation 115 SIGSYS create core image system call given invalid 116 argument 117 SIGPIPE terminate process write on a pipe with no reader 118 SIGALRM terminate process real-time timer expired 119 SIGTERM terminate process software termination signal 120 SIGURG discard signal urgent condition present on 121 socket 122 SIGSTOP stop process stop (cannot be caught or 123 ignored) 124 SIGTSTP stop process stop signal generated from 125 keyboard 126 SIGCONT discard signal continue after stop 127 SIGCHLD discard signal child status has changed 128 SIGTTIN stop process background read attempted from 129 control terminal 130 SIGTTOU stop process background write attempted to 131 132 control terminal 133 SIGIO discard signal I/O is possible on a descriptor 134 (see fcntl(2)) 135 SIGXCPU terminate process cpu time limit exceeded (see 136 setrlimit(2)) 137 SIGXFSZ terminate process file size limit exceeded (see 138 setrlimit(2)) 139 SIGVTALRM terminate process virtual time alarm (see 140 setitimer(2)) 141 SIGPROF terminate process profiling timer alarm (see 142 setitimer(2)) 143 SIGWINCH discard signal Window size change 144 SIGINFO discard signal status request from keyboard 145 SIGUSR1 terminate process User defined signal 1 146 SIGUSR2 terminate process User defined signal 2 147 148NNOOTTEE 149 The mask specified in _a_c_t is not allowed to block SIGKILL or SIGSTOP This 150 is done silently by the system. 151 152RREETTUURRNN VVAALLUUEESS 153 A 0 value indicated that the call succeeded. A -1 return value indicates 154 an error occurred and _e_r_r_n_o is set to indicated the reason. 155 156EERRRROORR 157 SSiiggaaccttiioonn() will fail and no new signal handler will be installed if one 158 of the following occurs: Either _a_c_t or _o_a_c_t points to memory that is not 159 a valid part of the process address space. _S_i_g is not a valid signal 160 number. An attempt is made to ignore or supply a handler for _S_I_G_K_I_L or 161 SIGSTOP 162 163SSTTAANNDDAARRDD 164 The ssiiggaaccttiioonn function is defined by IEEE Std1003.1-1988 (``POSIX''). The 165 SA_ONSTACK and SA_RESTART flags are Berkeley extensions, as are the 166 signals, SIGTRAP, SIGEMT, SIGBUS, SIGSYS, SIGURG, SIGIO, SIGXCPU, 167 SIGXFSZ, SIGVTALRM, SIGPROF, SIGWINCH, and SIGINFO. Most of those signals 168 are available on most BSD-derived systems. 169 170SSEEEE AALLSSOO 171 kill(1), ptrace(2), kill(2), sigaction(2), sigprocmask(2), _s_i_g_s_e_t_o_p_s 172 _2, sigsuspend(2), sigblock(2), sigsetmask(2), sigpause(2), 173 sigstack(2), sigvec(2), setjmp(3), _s_i_g_i_n_t_e_r_r_u_p_t _3, tty(4) 174 175EEXXAAMMPPLLEE 176 On a VAX-11, the handler routine can be declared: 177 178 void handler(sig, code, scp) 179 int sig, code; 180 struct sigcontext *scp; 181 182 Here _s_i_g is the signal number, into which the hardware faults and traps 183 are mapped as defined below. _C_o_d_e is a parameter that is either a 184 constant as given below or the code provided by the hardware 185 (Compatibility mode faults are distinguished from the other SIGILL traps 186 by having PSL_CM set in the psl). _S_c_p is a pointer to the _s_i_g_c_o_n_t_e_x_t 187 structure (defined in <_s_i_g_n_a_l._h>), used to restore the context from 188 before the signal. 189 190BSD Experimental July 23, 1991 3 191 192 193 194 195 196 197 198 199