Commit | Line | Data |
---|---|---|
87714767 MK |
1 | .\" Copyright (c) 1980, 1990 The Regents of the University of California. |
2 | .\" All rights reserved. | |
3 | .\" | |
faf7e3e0 | 4 | .\" %sccs.include.redist.roff% |
87714767 | 5 | .\" |
faf7e3e0 | 6 | .\" @(#)sigaction.2 6.3 (Berkeley) %G% |
87714767 | 7 | .\" |
e17b717a CL |
8 | .Dd |
9 | .Dt SIGACTION 2 | |
faf7e3e0 | 10 | .Os |
e17b717a CL |
11 | .Sh NAME |
12 | .Nm sigaction | |
13 | .Nd software signal facilities | |
14 | .Sh SYNOPSIS | |
15 | .Fd #include <signal.h> | |
16 | .Bd -literal | |
17 | struct sigaction { | |
18 | void (*sa_handler)(); | |
19 | sigset_t sa_mask; | |
20 | int sa_flags; | |
21 | }; | |
22 | .Ed | |
23 | .Fn sigaction "int sig" "struct sigaction *act" "struct sigaction *oact" | |
24 | .Sh DESCRIPTION | |
87714767 MK |
25 | The system defines a set of signals that may be delivered to a process. |
26 | Signal delivery resembles the occurence of a hardware interrupt: | |
27 | the signal is blocked from further occurrence, the current process | |
28 | context is saved, and a new one is built. A process may specify a | |
e17b717a | 29 | .Em handler |
87714767 | 30 | to which a signal is delivered, or specify that a signal is to be |
e17b717a | 31 | .Em ignored . |
87714767 MK |
32 | A process may also specify that a default action is to be taken |
33 | by the system when a signal occurs. | |
34 | A signal may also be | |
e17b717a | 35 | .Em blocked , |
87714767 | 36 | in which case its delivery is postponed until it is |
e17b717a | 37 | .Em unblocked . |
87714767 MK |
38 | The action to be taken on delivery is determined at the time |
39 | of delivery. | |
40 | Normally, signal handlers execute on the current stack | |
41 | of the process. This may be changed, on a per-handler basis, | |
42 | so that signals are taken on a special | |
e17b717a CL |
43 | .Em "signal stack" . |
44 | .Pp | |
87714767 MK |
45 | Signal routines execute with the signal that caused their |
46 | invocation | |
e17b717a | 47 | .Em blocked , |
87714767 MK |
48 | but other signals may yet occur. |
49 | A global | |
e17b717a | 50 | .Em "signal mask" |
87714767 MK |
51 | defines the set of signals currently blocked from delivery |
52 | to a process. The signal mask for a process is initialized | |
53 | from that of its parent (normally empty). It | |
54 | may be changed with a | |
e17b717a | 55 | .Xr sigprocmask 2 |
87714767 | 56 | call, or when a signal is delivered to the process. |
e17b717a | 57 | .Pp |
87714767 MK |
58 | When a signal |
59 | condition arises for a process, the signal is added to a set of | |
60 | signals pending for the process. | |
61 | If the signal is not currently | |
e17b717a | 62 | .Em blocked |
87714767 MK |
63 | by the process then it is delivered to the process. |
64 | Signals may be delivered any time a process enters the operating system | |
65 | (e.g., during a system call, page fault or trap, or clock interrupt). | |
66 | If multiple signals are ready to be delivered at the same time, | |
67 | any signals that could be caused by traps are delivered first. | |
68 | Additional signals may be processed at the same time, with each | |
69 | appearing to interrupt the handlers for the previous signals | |
70 | before their first instructions. | |
71 | The set of pending signals is returned by the | |
e17b717a | 72 | .Xr sigpending 2 |
87714767 MK |
73 | function. |
74 | When a caught signal | |
75 | is delivered, the current state of the process is saved, | |
76 | a new signal mask is calculated (as described below), | |
77 | and the signal handler is invoked. The call to the handler | |
78 | is arranged so that if the signal handling routine returns | |
79 | normally the process will resume execution in the context | |
80 | from before the signal's delivery. | |
81 | If the process wishes to resume in a different context, then it | |
82 | must arrange to restore the previous context itself. | |
e17b717a | 83 | .Pp |
87714767 MK |
84 | When a signal is delivered to a process a new signal mask is |
85 | installed for the duration of the process' signal handler | |
86 | (or until a | |
e17b717a | 87 | .Xr sigprocmask |
87714767 MK |
88 | call is made). |
89 | This mask is formed by taking the union of the current signal mask set, | |
90 | the signal to be delivered, and | |
91 | the signal mask associated with the handler to be invoked. | |
e17b717a CL |
92 | .Pp |
93 | .Fn Sigaction | |
87714767 MK |
94 | assigns an action for a specific signal. |
95 | If | |
e17b717a | 96 | .Fa act |
87714767 | 97 | is non-zero, it |
e17b717a CL |
98 | specifies an action |
99 | .Pf ( Dv SIG_DFL , | |
100 | .Dv SIG_IGN , | |
101 | or a handler routine) and mask | |
87714767 MK |
102 | to be used when delivering the specified signal. |
103 | If | |
e17b717a | 104 | .Fa oact |
87714767 MK |
105 | is non-zero, the previous handling information for the signal |
106 | is returned to the user. | |
e17b717a | 107 | .Pp |
87714767 MK |
108 | Once a signal handler is installed, it remains installed |
109 | until another | |
e17b717a | 110 | .Fn sigaction |
87714767 | 111 | call is made, or an |
e17b717a | 112 | .Xr execve 2 |
87714767 | 113 | is performed. |
e17b717a CL |
114 | A signal-specific default action may be reset by |
115 | setting | |
116 | .Fa sa_handler | |
117 | to | |
118 | .Dv SIG_DFL . | |
119 | The defaults are process termination, possibly with core dump; | |
87714767 MK |
120 | no action; stopping the process; or continuing the process. |
121 | See the signal list below for each signal's default action. | |
122 | If | |
e17b717a CL |
123 | .Fa sa_handler |
124 | is | |
125 | .Dv SIG_IGN | |
126 | current and pending instances | |
127 | of the signal are ignored and discarded. | |
128 | .Pp | |
87714767 | 129 | Options may be specified by setting |
e17b717a CL |
130 | .Em sa_flags . |
131 | If the | |
132 | .Dv SA_NOCLDSTOP | |
133 | bit is set when installing a catching function | |
134 | for the | |
135 | .Dv SIGCHLD | |
136 | signal, | |
137 | the | |
138 | .Dv SIGCHLD | |
139 | signal will be generated only when a child process exits, | |
87714767 | 140 | not when a child process stops. |
e17b717a CL |
141 | Further, if the |
142 | .Dv SA_ONSTACK | |
143 | bit is set in | |
144 | .Em sa_flags , | |
87714767 | 145 | the system will deliver the signal to the process on a |
e17b717a | 146 | .Em "signal stack" , |
87714767 | 147 | specified with |
e17b717a CL |
148 | .Xr sigstack 2 . |
149 | .Pp | |
150 | If a signal is caught during the system calls listed below, | |
151 | the call may be forced to terminate | |
152 | with the error | |
153 | .Dv EINTR , | |
87714767 MK |
154 | or the call may be restarted. |
155 | Restart of pending calls is requested | |
e17b717a CL |
156 | by setting the |
157 | .Dv SA_RESTART | |
158 | bit in | |
159 | .Ar sa_flags . | |
87714767 | 160 | The affected system calls include |
e17b717a CL |
161 | .Xr read 2 , |
162 | .Xr write 2 , | |
163 | .Xr sendto 2 , | |
164 | .Xr recvfrom 2 , | |
165 | .Xr sendmsg 2 | |
87714767 | 166 | and |
e17b717a | 167 | .Xr recvmsg 2 |
87714767 MK |
168 | on a communications channel or a slow device (such as a terminal, |
169 | but not a regular file) | |
170 | and during a | |
e17b717a | 171 | .Xr wait 2 |
87714767 | 172 | or |
e17b717a | 173 | .Xr ioctl 2 . |
87714767 MK |
174 | However, calls that have already committed are not restarted, |
175 | but instead return a partial success (for example, a short read count). | |
e17b717a | 176 | .Pp |
87714767 | 177 | After a |
e17b717a | 178 | .Xr fork 2 |
87714767 | 179 | or |
e17b717a | 180 | .Xr vfork 2 |
87714767 | 181 | all signals, the signal mask, the signal stack, |
e17b717a CL |
182 | and the restart/interrupt flags are inherited by the child. |
183 | .Pp | |
184 | .Xr Execve 2 | |
185 | reinstates the default | |
186 | action for all signals which were caught and | |
87714767 MK |
187 | resets all signals to be caught on the user stack. |
188 | Ignored signals remain ignored; | |
189 | the signal mask remains the same; | |
190 | signals that restart pending system calls continue to do so. | |
e17b717a | 191 | .Pp |
87714767 MK |
192 | The following is a list of all signals |
193 | with names as in the include file | |
e17b717a CL |
194 | .Aq Pa signal.h : |
195 | .Bl -column SIGVTALARMXX "create core imagexxx" | |
196 | .It Sy " NAME " " Default Action " " Description" | |
197 | .It Dv SIGHUP No " terminate process" " terminal line hangup" | |
198 | .It Dv SIGINT No " terminate process" " interrupt program" | |
199 | .It Dv SIGQUIT No " create core image" " quit program" | |
200 | .It Dv SIGILL No " create core image" " illegal instruction" | |
201 | .It Dv SIGTRAP No " create core image" " trace trap" | |
202 | .It Dv SIGABRT No " create core image" Xr abort 2 | |
203 | call (formerly | |
204 | .Dv SIGIOT ) | |
205 | .It Dv SIGEMT No " create core image" " emulate instruction executed" | |
206 | .It Dv SIGFPE No " create core image" " floating-point exception" | |
207 | .It Dv SIGKILL No " terminate process" " kill program" | |
208 | .It Dv SIGBUS No " create core image" " bus error" | |
209 | .It Dv SIGSEGV No " create core image" " segmentation violation" | |
210 | .It Dv SIGSYS No " create core image" " system call given invalid argument" | |
211 | .It Dv SIGPIPE No " terminate process" " write on a pipe with no reader" | |
212 | .It Dv SIGALRM No " terminate process" " real-time timer expired" | |
213 | .It Dv SIGTERM No " terminate process" " software termination signal" | |
214 | .It Dv SIGURG No " discard signal" " urgent condition present on socket" | |
215 | .It Dv SIGSTOP No " stop process" " stop (cannot be caught or ignored)" | |
216 | .It Dv SIGTSTP No " stop process" " stop signal generated from keyboard" | |
217 | .It Dv SIGCONT No " discard signal" " continue after stop" | |
218 | .It Dv SIGCHLD No " discard signal" " child status has changed" | |
219 | .It Dv SIGTTIN No " stop process" " background read attempted from control terminal" | |
220 | .It Dv SIGTTOU No " stop process" " background write attempted to control terminal" | |
221 | .It Dv SIGIO No " discard signal" Tn " I/O" | |
222 | is possible on a descriptor (see | |
223 | .Xr fcntl 2 ) | |
224 | .It Dv SIGXCPU No " terminate process" " cpu time limit exceeded (see" | |
225 | .Xr setrlimit 2 ) | |
226 | .It Dv SIGXFSZ No " terminate process" " file size limit exceeded (see" | |
227 | .Xr setrlimit 2 ) | |
228 | .It Dv SIGVTALRM No " terminate process" " virtual time alarm (see" | |
229 | .Xr setitimer 2 ) | |
230 | .It Dv SIGPROF No " terminate process" " profiling timer alarm (see" | |
231 | .Xr setitimer 2 ) | |
232 | .It Dv SIGWINCH No " discard signal" " Window size change" | |
233 | .It Dv SIGINFO No " discard signal" " status request from keyboard" | |
234 | .It Dv SIGUSR1 No " terminate process" " User defined signal 1" | |
235 | .It Dv SIGUSR2 No " terminate process" " User defined signal 2" | |
236 | .El | |
237 | .Sh NOTE | |
87714767 | 238 | The mask specified in |
e17b717a CL |
239 | .Fa act |
240 | is not allowed to block | |
241 | .Dv SIGKILL | |
242 | or | |
243 | .Dv SIGSTOP | |
87714767 | 244 | This is done silently by the system. |
e17b717a | 245 | .Sh RETURN VALUES |
87714767 MK |
246 | A 0 value indicated that the call succeeded. A \-1 return value |
247 | indicates an error occurred and | |
e17b717a | 248 | .Va errno |
87714767 | 249 | is set to indicated the reason. |
e17b717a CL |
250 | .Sh ERROR |
251 | .Fn Sigaction | |
87714767 MK |
252 | will fail and no new signal handler will be installed if one |
253 | of the following occurs: | |
e17b717a CL |
254 | .Tw Er |
255 | .Tl Bq Er EFAULT | |
87714767 | 256 | Either |
e17b717a | 257 | .Fa act |
87714767 | 258 | or |
e17b717a | 259 | .Fa oact |
87714767 MK |
260 | points to memory that is not a valid part of the process |
261 | address space. | |
e17b717a CL |
262 | .Tl Bq Er EINVAL |
263 | .Fa Sig | |
87714767 | 264 | is not a valid signal number. |
e17b717a CL |
265 | .Tl Bq Er EINVAL |
266 | An attempt is made to ignore or supply a handler for | |
267 | .Em SIGKIL | |
268 | or | |
269 | .Dv SIGSTOP | |
270 | .Tl | |
271 | .Sh STANDARD | |
272 | The | |
faf7e3e0 | 273 | .Nm sigaction |
e17b717a CL |
274 | function is defined by |
275 | .St -p1003.1-88 . | |
87714767 | 276 | The |
e17b717a CL |
277 | .Dv SA_ONSTACK |
278 | and | |
279 | .Dv SA_RESTART | |
280 | flags are Berkeley extensions, | |
281 | as are the signals, | |
282 | .Dv SIGTRAP , | |
283 | .Dv SIGEMT , | |
284 | .Dv SIGBUS , | |
285 | .Dv SIGSYS , | |
286 | .Dv SIGURG , | |
287 | .Dv SIGIO , | |
288 | .Dv SIGXCPU , | |
289 | .Dv SIGXFSZ , | |
290 | .Dv SIGVTALRM , | |
291 | .Dv SIGPROF , | |
292 | .Dv SIGWINCH , | |
293 | and | |
294 | .Dv SIGINFO . | |
295 | Most of those signals are available on most | |
296 | .Tn BSD Ns \-derived | |
297 | systems. | |
298 | .Sh SEE ALSO | |
299 | .Xr kill 1 , | |
300 | .Xr ptrace 2 , | |
301 | .Xr kill 2 , | |
302 | .Xr sigaction 2 , | |
303 | .Xr sigprocmask 2 , | |
304 | .Em sigsetops 2 , | |
305 | .Xr sigsuspend 2 , | |
306 | .Xr sigblock 2 , | |
307 | .Xr sigsetmask 2 , | |
308 | .Xr sigpause 2 , | |
309 | .Xr sigstack 2 , | |
310 | .Xr sigvec 2 , | |
311 | .Xr setjmp 3 , | |
312 | .Em siginterrupt 3 , | |
313 | .Xr tty 4 | |
314 | .Sh EXAMPLE | |
315 | On a | |
316 | .Tn VAX\-11, | |
317 | the handler routine can be declared: | |
318 | .Bd -literal -offset indent | |
319 | void handler(sig, code, scp) | |
320 | int sig, code; | |
321 | struct sigcontext *scp; | |
322 | .Ed | |
323 | .Pp | |
87714767 | 324 | Here |
e17b717a | 325 | .Fa sig |
87714767 MK |
326 | is the signal number, into which the hardware faults and traps are |
327 | mapped as defined below. | |
e17b717a | 328 | .Em Code |
87714767 | 329 | is a parameter that is either a constant |
e17b717a | 330 | as given below or the code provided by |
87714767 | 331 | the hardware (Compatibility mode faults are distinguished from the |
e17b717a CL |
332 | other |
333 | .Dv SIGILL | |
334 | traps by having | |
335 | .Dv PSL_CM | |
336 | set in the psl). | |
337 | .Fa Scp | |
87714767 | 338 | is a pointer to the |
e17b717a | 339 | .Fa sigcontext |
87714767 | 340 | structure (defined in |
e17b717a | 341 | .Aq Pa signal.h ) , |
87714767 | 342 | used to restore the context from before the signal. |