]>
Commit | Line | Data |
---|---|---|
17c389fc | 1 | @node Signal Handling, Program Basics, Non-Local Exits, Top |
7a68c94a | 2 | @c %MENU% How to send, block, and handle signals |
28f540f4 RM |
3 | @chapter Signal Handling |
4 | ||
5 | @cindex signal | |
6 | A @dfn{signal} is a software interrupt delivered to a process. The | |
7 | operating system uses signals to report exceptional situations to an | |
8 | executing program. Some signals report errors such as references to | |
9 | invalid memory addresses; others report asynchronous events, such as | |
10 | disconnection of a phone line. | |
11 | ||
1f77f049 | 12 | @Theglibc{} defines a variety of signal types, each for a |
28f540f4 RM |
13 | particular kind of event. Some kinds of events make it inadvisable or |
14 | impossible for the program to proceed as usual, and the corresponding | |
15 | signals normally abort the program. Other kinds of signals that report | |
16 | harmless events are ignored by default. | |
17 | ||
18 | If you anticipate an event that causes signals, you can define a handler | |
19 | function and tell the operating system to run it when that particular | |
20 | type of signal arrives. | |
21 | ||
22 | Finally, one process can send a signal to another process; this allows a | |
23 | parent process to abort a child, or two related processes to communicate | |
24 | and synchronize. | |
25 | ||
26 | @menu | |
27 | * Concepts of Signals:: Introduction to the signal facilities. | |
28 | * Standard Signals:: Particular kinds of signals with | |
29 | standard names and meanings. | |
30 | * Signal Actions:: Specifying what happens when a | |
31 | particular signal is delivered. | |
32 | * Defining Handlers:: How to write a signal handler function. | |
33 | * Interrupted Primitives:: Signal handlers affect use of @code{open}, | |
34 | @code{read}, @code{write} and other functions. | |
35 | * Generating Signals:: How to send a signal to a process. | |
36 | * Blocking Signals:: Making the system hold signals temporarily. | |
37 | * Waiting for a Signal:: Suspending your program until a signal | |
f65fd747 | 38 | arrives. |
28f540f4 RM |
39 | * Signal Stack:: Using a Separate Signal Stack. |
40 | * BSD Signal Handling:: Additional functions for backward | |
41 | compatibility with BSD. | |
42 | @end menu | |
43 | ||
44 | @node Concepts of Signals | |
45 | @section Basic Concepts of Signals | |
46 | ||
47 | This section explains basic concepts of how signals are generated, what | |
48 | happens after a signal is delivered, and how programs can handle | |
49 | signals. | |
50 | ||
51 | @menu | |
52 | * Kinds of Signals:: Some examples of what can cause a signal. | |
53 | * Signal Generation:: Concepts of why and how signals occur. | |
54 | * Delivery of Signal:: Concepts of what a signal does to the | |
f65fd747 | 55 | process. |
28f540f4 RM |
56 | @end menu |
57 | ||
58 | @node Kinds of Signals | |
f65fd747 | 59 | @subsection Some Kinds of Signals |
28f540f4 RM |
60 | |
61 | A signal reports the occurrence of an exceptional event. These are some | |
62 | of the events that can cause (or @dfn{generate}, or @dfn{raise}) a | |
63 | signal: | |
64 | ||
65 | @itemize @bullet | |
66 | @item | |
67 | A program error such as dividing by zero or issuing an address outside | |
68 | the valid range. | |
69 | ||
70 | @item | |
71 | A user request to interrupt or terminate the program. Most environments | |
72 | are set up to let a user suspend the program by typing @kbd{C-z}, or | |
73 | terminate it with @kbd{C-c}. Whatever key sequence is used, the | |
74 | operating system sends the proper signal to interrupt the process. | |
75 | ||
76 | @item | |
77 | The termination of a child process. | |
78 | ||
79 | @item | |
80 | Expiration of a timer or alarm. | |
81 | ||
82 | @item | |
83 | A call to @code{kill} or @code{raise} by the same process. | |
84 | ||
85 | @item | |
86 | A call to @code{kill} from another process. Signals are a limited but | |
87 | useful form of interprocess communication. | |
88 | ||
89 | @item | |
90 | An attempt to perform an I/O operation that cannot be done. Examples | |
91 | are reading from a pipe that has no writer (@pxref{Pipes and FIFOs}), | |
92 | and reading or writing to a terminal in certain situations (@pxref{Job | |
93 | Control}). | |
94 | @end itemize | |
95 | ||
96 | Each of these kinds of events (excepting explicit calls to @code{kill} | |
97 | and @code{raise}) generates its own particular kind of signal. The | |
98 | various kinds of signals are listed and described in detail in | |
99 | @ref{Standard Signals}. | |
100 | ||
101 | @node Signal Generation | |
102 | @subsection Concepts of Signal Generation | |
103 | @cindex generation of signals | |
104 | ||
105 | In general, the events that generate signals fall into three major | |
106 | categories: errors, external events, and explicit requests. | |
107 | ||
108 | An error means that a program has done something invalid and cannot | |
109 | continue execution. But not all kinds of errors generate signals---in | |
110 | fact, most do not. For example, opening a nonexistent file is an error, | |
111 | but it does not raise a signal; instead, @code{open} returns @code{-1}. | |
112 | In general, errors that are necessarily associated with certain library | |
113 | functions are reported by returning a value that indicates an error. | |
114 | The errors which raise signals are those which can happen anywhere in | |
115 | the program, not just in library calls. These include division by zero | |
116 | and invalid memory addresses. | |
117 | ||
118 | An external event generally has to do with I/O or other processes. | |
119 | These include the arrival of input, the expiration of a timer, and the | |
120 | termination of a child process. | |
121 | ||
122 | An explicit request means the use of a library function such as | |
123 | @code{kill} whose purpose is specifically to generate a signal. | |
124 | ||
125 | Signals may be generated @dfn{synchronously} or @dfn{asynchronously}. A | |
126 | synchronous signal pertains to a specific action in the program, and is | |
127 | delivered (unless blocked) during that action. Most errors generate | |
128 | signals synchronously, and so do explicit requests by a process to | |
129 | generate a signal for that same process. On some machines, certain | |
130 | kinds of hardware errors (usually floating-point exceptions) are not | |
131 | reported completely synchronously, but may arrive a few instructions | |
132 | later. | |
133 | ||
134 | Asynchronous signals are generated by events outside the control of the | |
135 | process that receives them. These signals arrive at unpredictable times | |
136 | during execution. External events generate signals asynchronously, and | |
137 | so do explicit requests that apply to some other process. | |
138 | ||
6d52618b | 139 | A given type of signal is either typically synchronous or typically |
28f540f4 RM |
140 | asynchronous. For example, signals for errors are typically synchronous |
141 | because errors generate signals synchronously. But any type of signal | |
142 | can be generated synchronously or asynchronously with an explicit | |
143 | request. | |
144 | ||
145 | @node Delivery of Signal | |
146 | @subsection How Signals Are Delivered | |
147 | @cindex delivery of signals | |
148 | @cindex pending signals | |
149 | @cindex blocked signals | |
150 | ||
151 | When a signal is generated, it becomes @dfn{pending}. Normally it | |
152 | remains pending for just a short period of time and then is | |
153 | @dfn{delivered} to the process that was signaled. However, if that kind | |
154 | of signal is currently @dfn{blocked}, it may remain pending | |
155 | indefinitely---until signals of that kind are @dfn{unblocked}. Once | |
156 | unblocked, it will be delivered immediately. @xref{Blocking Signals}. | |
157 | ||
158 | @cindex specified action (for a signal) | |
159 | @cindex default action (for a signal) | |
160 | @cindex signal action | |
161 | @cindex catching signals | |
162 | When the signal is delivered, whether right away or after a long delay, | |
163 | the @dfn{specified action} for that signal is taken. For certain | |
164 | signals, such as @code{SIGKILL} and @code{SIGSTOP}, the action is fixed, | |
165 | but for most signals, the program has a choice: ignore the signal, | |
166 | specify a @dfn{handler function}, or accept the @dfn{default action} for | |
167 | that kind of signal. The program specifies its choice using functions | |
168 | such as @code{signal} or @code{sigaction} (@pxref{Signal Actions}). We | |
169 | sometimes say that a handler @dfn{catches} the signal. While the | |
170 | handler is running, that particular signal is normally blocked. | |
171 | ||
172 | If the specified action for a kind of signal is to ignore it, then any | |
173 | such signal which is generated is discarded immediately. This happens | |
174 | even if the signal is also blocked at the time. A signal discarded in | |
175 | this way will never be delivered, not even if the program subsequently | |
176 | specifies a different action for that kind of signal and then unblocks | |
177 | it. | |
178 | ||
179 | If a signal arrives which the program has neither handled nor ignored, | |
180 | its @dfn{default action} takes place. Each kind of signal has its own | |
181 | default action, documented below (@pxref{Standard Signals}). For most kinds | |
182 | of signals, the default action is to terminate the process. For certain | |
183 | kinds of signals that represent ``harmless'' events, the default action | |
184 | is to do nothing. | |
185 | ||
186 | When a signal terminates a process, its parent process can determine the | |
187 | cause of termination by examining the termination status code reported | |
188 | by the @code{wait} or @code{waitpid} functions. (This is discussed in | |
189 | more detail in @ref{Process Completion}.) The information it can get | |
bafb8ee9 | 190 | includes the fact that termination was due to a signal and the kind of |
28f540f4 RM |
191 | signal involved. If a program you run from a shell is terminated by a |
192 | signal, the shell typically prints some kind of error message. | |
193 | ||
194 | The signals that normally represent program errors have a special | |
195 | property: when one of these signals terminates the process, it also | |
196 | writes a @dfn{core dump file} which records the state of the process at | |
197 | the time of termination. You can examine the core dump with a debugger | |
198 | to investigate what caused the error. | |
199 | ||
200 | If you raise a ``program error'' signal by explicit request, and this | |
201 | terminates the process, it makes a core dump file just as if the signal | |
202 | had been due directly to an error. | |
203 | ||
204 | @node Standard Signals | |
205 | @section Standard Signals | |
206 | @cindex signal names | |
207 | @cindex names of signals | |
208 | ||
209 | @pindex signal.h | |
210 | @cindex signal number | |
211 | This section lists the names for various standard kinds of signals and | |
212 | describes what kind of event they mean. Each signal name is a macro | |
213 | which stands for a positive integer---the @dfn{signal number} for that | |
214 | kind of signal. Your programs should never make assumptions about the | |
215 | numeric code for a particular kind of signal, but rather refer to them | |
216 | always by the names defined here. This is because the number for a | |
217 | given kind of signal can vary from system to system, but the meanings of | |
218 | the names are standardized and fairly uniform. | |
219 | ||
220 | The signal names are defined in the header file @file{signal.h}. | |
221 | ||
222 | @comment signal.h | |
223 | @comment BSD | |
224 | @deftypevr Macro int NSIG | |
225 | The value of this symbolic constant is the total number of signals | |
226 | defined. Since the signal numbers are allocated consecutively, | |
227 | @code{NSIG} is also one greater than the largest defined signal number. | |
228 | @end deftypevr | |
229 | ||
230 | @menu | |
231 | * Program Error Signals:: Used to report serious program errors. | |
232 | * Termination Signals:: Used to interrupt and/or terminate the | |
f65fd747 | 233 | program. |
28f540f4 RM |
234 | * Alarm Signals:: Used to indicate expiration of timers. |
235 | * Asynchronous I/O Signals:: Used to indicate input is available. | |
236 | * Job Control Signals:: Signals used to support job control. | |
237 | * Operation Error Signals:: Used to report operational system errors. | |
238 | * Miscellaneous Signals:: Miscellaneous Signals. | |
239 | * Signal Messages:: Printing a message describing a signal. | |
240 | @end menu | |
241 | ||
242 | @node Program Error Signals | |
243 | @subsection Program Error Signals | |
244 | @cindex program error signals | |
245 | ||
246 | The following signals are generated when a serious program error is | |
247 | detected by the operating system or the computer itself. In general, | |
248 | all of these signals are indications that your program is seriously | |
249 | broken in some way, and there's usually no way to continue the | |
250 | computation which encountered the error. | |
251 | ||
252 | Some programs handle program error signals in order to tidy up before | |
253 | terminating; for example, programs that turn off echoing of terminal | |
254 | input should handle program error signals in order to turn echoing back | |
255 | on. The handler should end by specifying the default action for the | |
256 | signal that happened and then reraising it; this will cause the program | |
257 | to terminate with that signal, as if it had not had a handler. | |
258 | (@xref{Termination in Handler}.) | |
259 | ||
260 | Termination is the sensible ultimate outcome from a program error in | |
261 | most programs. However, programming systems such as Lisp that can load | |
262 | compiled user programs might need to keep executing even if a user | |
263 | program incurs an error. These programs have handlers which use | |
264 | @code{longjmp} to return control to the command level. | |
265 | ||
266 | The default action for all of these signals is to cause the process to | |
267 | terminate. If you block or ignore these signals or establish handlers | |
268 | for them that return normally, your program will probably break horribly | |
269 | when such signals happen, unless they are generated by @code{raise} or | |
270 | @code{kill} instead of a real error. | |
271 | ||
272 | @vindex COREFILE | |
273 | When one of these program error signals terminates a process, it also | |
274 | writes a @dfn{core dump file} which records the state of the process at | |
275 | the time of termination. The core dump file is named @file{core} and is | |
276 | written in whichever directory is current in the process at the time. | |
a7a93d50 | 277 | (On @gnuhurdsystems{}, you can specify the file name for core dumps with |
28f540f4 RM |
278 | the environment variable @code{COREFILE}.) The purpose of core dump |
279 | files is so that you can examine them with a debugger to investigate | |
280 | what caused the error. | |
281 | ||
282 | @comment signal.h | |
f65fd747 | 283 | @comment ISO |
28f540f4 RM |
284 | @deftypevr Macro int SIGFPE |
285 | The @code{SIGFPE} signal reports a fatal arithmetic error. Although the | |
286 | name is derived from ``floating-point exception'', this signal actually | |
287 | covers all arithmetic errors, including division by zero and overflow. | |
288 | If a program stores integer data in a location which is then used in a | |
289 | floating-point operation, this often causes an ``invalid operation'' | |
290 | exception, because the processor cannot recognize the data as a | |
291 | floating-point number. | |
292 | @cindex exception | |
293 | @cindex floating-point exception | |
294 | ||
295 | Actual floating-point exceptions are a complicated subject because there | |
296 | are many types of exceptions with subtly different meanings, and the | |
297 | @code{SIGFPE} signal doesn't distinguish between them. The @cite{IEEE | |
f65fd747 UD |
298 | Standard for Binary Floating-Point Arithmetic (ANSI/IEEE Std 754-1985 |
299 | and ANSI/IEEE Std 854-1987)} | |
28f540f4 RM |
300 | defines various floating-point exceptions and requires conforming |
301 | computer systems to report their occurrences. However, this standard | |
302 | does not specify how the exceptions are reported, or what kinds of | |
303 | handling and control the operating system can offer to the programmer. | |
304 | @end deftypevr | |
305 | ||
306 | BSD systems provide the @code{SIGFPE} handler with an extra argument | |
307 | that distinguishes various causes of the exception. In order to access | |
308 | this argument, you must define the handler to accept two arguments, | |
309 | which means you must cast it to a one-argument function type in order to | |
1f77f049 | 310 | establish the handler. @Theglibc{} does provide this extra |
28f540f4 | 311 | argument, but the value is meaningful only on operating systems that |
a7a93d50 | 312 | provide the information (BSD systems and @gnusystems{}). |
28f540f4 RM |
313 | |
314 | @table @code | |
315 | @comment signal.h | |
316 | @comment BSD | |
317 | @item FPE_INTOVF_TRAP | |
318 | @vindex FPE_INTOVF_TRAP | |
319 | Integer overflow (impossible in a C program unless you enable overflow | |
320 | trapping in a hardware-specific fashion). | |
321 | @comment signal.h | |
322 | @comment BSD | |
323 | @item FPE_INTDIV_TRAP | |
324 | @vindex FPE_INTDIV_TRAP | |
325 | Integer division by zero. | |
326 | @comment signal.h | |
327 | @comment BSD | |
328 | @item FPE_SUBRNG_TRAP | |
329 | @vindex FPE_SUBRNG_TRAP | |
330 | Subscript-range (something that C programs never check for). | |
331 | @comment signal.h | |
332 | @comment BSD | |
333 | @item FPE_FLTOVF_TRAP | |
334 | @vindex FPE_FLTOVF_TRAP | |
335 | Floating overflow trap. | |
336 | @comment signal.h | |
337 | @comment BSD | |
338 | @item FPE_FLTDIV_TRAP | |
339 | @vindex FPE_FLTDIV_TRAP | |
340 | Floating/decimal division by zero. | |
341 | @comment signal.h | |
342 | @comment BSD | |
343 | @item FPE_FLTUND_TRAP | |
344 | @vindex FPE_FLTUND_TRAP | |
345 | Floating underflow trap. (Trapping on floating underflow is not | |
346 | normally enabled.) | |
347 | @comment signal.h | |
348 | @comment BSD | |
349 | @item FPE_DECOVF_TRAP | |
350 | @vindex FPE_DECOVF_TRAP | |
351 | Decimal overflow trap. (Only a few machines have decimal arithmetic and | |
352 | C never uses it.) | |
353 | @ignore @c These seem redundant | |
354 | @comment signal.h | |
355 | @comment BSD | |
356 | @item FPE_FLTOVF_FAULT | |
357 | @vindex FPE_FLTOVF_FAULT | |
358 | Floating overflow fault. | |
359 | @comment signal.h | |
360 | @comment BSD | |
361 | @item FPE_FLTDIV_FAULT | |
362 | @vindex FPE_FLTDIV_FAULT | |
363 | Floating divide by zero fault. | |
364 | @comment signal.h | |
365 | @comment BSD | |
366 | @item FPE_FLTUND_FAULT | |
367 | @vindex FPE_FLTUND_FAULT | |
368 | Floating underflow fault. | |
369 | @end ignore | |
370 | @end table | |
371 | ||
372 | @comment signal.h | |
f65fd747 | 373 | @comment ISO |
28f540f4 RM |
374 | @deftypevr Macro int SIGILL |
375 | The name of this signal is derived from ``illegal instruction''; it | |
376 | usually means your program is trying to execute garbage or a privileged | |
377 | instruction. Since the C compiler generates only valid instructions, | |
378 | @code{SIGILL} typically indicates that the executable file is corrupted, | |
379 | or that you are trying to execute data. Some common ways of getting | |
380 | into the latter situation are by passing an invalid object where a | |
381 | pointer to a function was expected, or by writing past the end of an | |
382 | automatic array (or similar problems with pointers to automatic | |
383 | variables) and corrupting other data on the stack such as the return | |
384 | address of a stack frame. | |
385 | ||
386 | @code{SIGILL} can also be generated when the stack overflows, or when | |
387 | the system has trouble running the handler for a signal. | |
388 | @end deftypevr | |
389 | @cindex illegal instruction | |
390 | ||
391 | @comment signal.h | |
f65fd747 | 392 | @comment ISO |
28f540f4 RM |
393 | @deftypevr Macro int SIGSEGV |
394 | @cindex segmentation violation | |
395 | This signal is generated when a program tries to read or write outside | |
396 | the memory that is allocated for it, or to write memory that can only be | |
397 | read. (Actually, the signals only occur when the program goes far | |
398 | enough outside to be detected by the system's memory protection | |
399 | mechanism.) The name is an abbreviation for ``segmentation violation''. | |
400 | ||
401 | Common ways of getting a @code{SIGSEGV} condition include dereferencing | |
402 | a null or uninitialized pointer, or when you use a pointer to step | |
403 | through an array, but fail to check for the end of the array. It varies | |
404 | among systems whether dereferencing a null pointer generates | |
405 | @code{SIGSEGV} or @code{SIGBUS}. | |
406 | @end deftypevr | |
407 | ||
408 | @comment signal.h | |
409 | @comment BSD | |
410 | @deftypevr Macro int SIGBUS | |
411 | This signal is generated when an invalid pointer is dereferenced. Like | |
412 | @code{SIGSEGV}, this signal is typically the result of dereferencing an | |
413 | uninitialized pointer. The difference between the two is that | |
414 | @code{SIGSEGV} indicates an invalid access to valid memory, while | |
415 | @code{SIGBUS} indicates an access to an invalid address. In particular, | |
416 | @code{SIGBUS} signals often result from dereferencing a misaligned | |
417 | pointer, such as referring to a four-word integer at an address not | |
418 | divisible by four. (Each kind of computer has its own requirements for | |
419 | address alignment.) | |
420 | ||
421 | The name of this signal is an abbreviation for ``bus error''. | |
422 | @end deftypevr | |
423 | @cindex bus error | |
424 | ||
425 | @comment signal.h | |
f65fd747 | 426 | @comment ISO |
28f540f4 RM |
427 | @deftypevr Macro int SIGABRT |
428 | @cindex abort signal | |
429 | This signal indicates an error detected by the program itself and | |
430 | reported by calling @code{abort}. @xref{Aborting a Program}. | |
431 | @end deftypevr | |
432 | ||
433 | @comment signal.h | |
434 | @comment Unix | |
435 | @deftypevr Macro int SIGIOT | |
436 | Generated by the PDP-11 ``iot'' instruction. On most machines, this is | |
437 | just another name for @code{SIGABRT}. | |
438 | @end deftypevr | |
439 | ||
440 | @comment signal.h | |
441 | @comment BSD | |
442 | @deftypevr Macro int SIGTRAP | |
443 | Generated by the machine's breakpoint instruction, and possibly other | |
444 | trap instructions. This signal is used by debuggers. Your program will | |
445 | probably only see @code{SIGTRAP} if it is somehow executing bad | |
446 | instructions. | |
447 | @end deftypevr | |
448 | ||
449 | @comment signal.h | |
450 | @comment BSD | |
451 | @deftypevr Macro int SIGEMT | |
452 | Emulator trap; this results from certain unimplemented instructions | |
453 | which might be emulated in software, or the operating system's | |
454 | failure to properly emulate them. | |
455 | @end deftypevr | |
456 | ||
457 | @comment signal.h | |
458 | @comment Unix | |
459 | @deftypevr Macro int SIGSYS | |
460 | Bad system call; that is to say, the instruction to trap to the | |
461 | operating system was executed, but the code number for the system call | |
462 | to perform was invalid. | |
463 | @end deftypevr | |
464 | ||
465 | @node Termination Signals | |
466 | @subsection Termination Signals | |
467 | @cindex program termination signals | |
468 | ||
469 | These signals are all used to tell a process to terminate, in one way | |
470 | or another. They have different names because they're used for slightly | |
471 | different purposes, and programs might want to handle them differently. | |
472 | ||
473 | The reason for handling these signals is usually so your program can | |
474 | tidy up as appropriate before actually terminating. For example, you | |
475 | might want to save state information, delete temporary files, or restore | |
476 | the previous terminal modes. Such a handler should end by specifying | |
477 | the default action for the signal that happened and then reraising it; | |
478 | this will cause the program to terminate with that signal, as if it had | |
479 | not had a handler. (@xref{Termination in Handler}.) | |
480 | ||
481 | The (obvious) default action for all of these signals is to cause the | |
482 | process to terminate. | |
483 | ||
484 | @comment signal.h | |
f65fd747 | 485 | @comment ISO |
28f540f4 RM |
486 | @deftypevr Macro int SIGTERM |
487 | @cindex termination signal | |
488 | The @code{SIGTERM} signal is a generic signal used to cause program | |
489 | termination. Unlike @code{SIGKILL}, this signal can be blocked, | |
490 | handled, and ignored. It is the normal way to politely ask a program to | |
491 | terminate. | |
492 | ||
493 | The shell command @code{kill} generates @code{SIGTERM} by default. | |
494 | @pindex kill | |
495 | @end deftypevr | |
496 | ||
497 | @comment signal.h | |
f65fd747 | 498 | @comment ISO |
28f540f4 RM |
499 | @deftypevr Macro int SIGINT |
500 | @cindex interrupt signal | |
501 | The @code{SIGINT} (``program interrupt'') signal is sent when the user | |
502 | types the INTR character (normally @kbd{C-c}). @xref{Special | |
503 | Characters}, for information about terminal driver support for | |
504 | @kbd{C-c}. | |
505 | @end deftypevr | |
506 | ||
507 | @comment signal.h | |
508 | @comment POSIX.1 | |
509 | @deftypevr Macro int SIGQUIT | |
510 | @cindex quit signal | |
511 | @cindex quit signal | |
512 | The @code{SIGQUIT} signal is similar to @code{SIGINT}, except that it's | |
513 | controlled by a different key---the QUIT character, usually | |
514 | @kbd{C-\}---and produces a core dump when it terminates the process, | |
515 | just like a program error signal. You can think of this as a | |
516 | program error condition ``detected'' by the user. | |
517 | ||
518 | @xref{Program Error Signals}, for information about core dumps. | |
519 | @xref{Special Characters}, for information about terminal driver | |
520 | support. | |
521 | ||
522 | Certain kinds of cleanups are best omitted in handling @code{SIGQUIT}. | |
523 | For example, if the program creates temporary files, it should handle | |
524 | the other termination requests by deleting the temporary files. But it | |
525 | is better for @code{SIGQUIT} not to delete them, so that the user can | |
526 | examine them in conjunction with the core dump. | |
527 | @end deftypevr | |
528 | ||
529 | @comment signal.h | |
530 | @comment POSIX.1 | |
531 | @deftypevr Macro int SIGKILL | |
532 | The @code{SIGKILL} signal is used to cause immediate program termination. | |
533 | It cannot be handled or ignored, and is therefore always fatal. It is | |
534 | also not possible to block this signal. | |
535 | ||
536 | This signal is usually generated only by explicit request. Since it | |
537 | cannot be handled, you should generate it only as a last resort, after | |
538 | first trying a less drastic method such as @kbd{C-c} or @code{SIGTERM}. | |
539 | If a process does not respond to any other termination signals, sending | |
540 | it a @code{SIGKILL} signal will almost always cause it to go away. | |
541 | ||
542 | In fact, if @code{SIGKILL} fails to terminate a process, that by itself | |
543 | constitutes an operating system bug which you should report. | |
544 | ||
545 | The system will generate @code{SIGKILL} for a process itself under some | |
a496e4ce | 546 | unusual conditions where the program cannot possibly continue to run |
28f540f4 RM |
547 | (even to run a signal handler). |
548 | @end deftypevr | |
549 | @cindex kill signal | |
550 | ||
551 | @comment signal.h | |
552 | @comment POSIX.1 | |
553 | @deftypevr Macro int SIGHUP | |
554 | @cindex hangup signal | |
555 | The @code{SIGHUP} (``hang-up'') signal is used to report that the user's | |
556 | terminal is disconnected, perhaps because a network or telephone | |
557 | connection was broken. For more information about this, see @ref{Control | |
558 | Modes}. | |
559 | ||
560 | This signal is also used to report the termination of the controlling | |
561 | process on a terminal to jobs associated with that session; this | |
562 | termination effectively disconnects all processes in the session from | |
563 | the controlling terminal. For more information, see @ref{Termination | |
564 | Internals}. | |
565 | @end deftypevr | |
566 | ||
567 | @node Alarm Signals | |
568 | @subsection Alarm Signals | |
569 | ||
570 | These signals are used to indicate the expiration of timers. | |
571 | @xref{Setting an Alarm}, for information about functions that cause | |
572 | these signals to be sent. | |
573 | ||
574 | The default behavior for these signals is to cause program termination. | |
575 | This default is rarely useful, but no other default would be useful; | |
576 | most of the ways of using these signals would require handler functions | |
577 | in any case. | |
578 | ||
579 | @comment signal.h | |
580 | @comment POSIX.1 | |
581 | @deftypevr Macro int SIGALRM | |
582 | This signal typically indicates expiration of a timer that measures real | |
583 | or clock time. It is used by the @code{alarm} function, for example. | |
584 | @end deftypevr | |
585 | @cindex alarm signal | |
586 | ||
587 | @comment signal.h | |
588 | @comment BSD | |
589 | @deftypevr Macro int SIGVTALRM | |
590 | This signal typically indicates expiration of a timer that measures CPU | |
591 | time used by the current process. The name is an abbreviation for | |
592 | ``virtual time alarm''. | |
593 | @end deftypevr | |
594 | @cindex virtual time alarm signal | |
595 | ||
596 | @comment signal.h | |
597 | @comment BSD | |
598 | @deftypevr Macro int SIGPROF | |
de71a46a | 599 | This signal typically indicates expiration of a timer that measures |
f65fd747 | 600 | both CPU time used by the current process, and CPU time expended on |
28f540f4 RM |
601 | behalf of the process by the system. Such a timer is used to implement |
602 | code profiling facilities, hence the name of this signal. | |
603 | @end deftypevr | |
604 | @cindex profiling alarm signal | |
605 | ||
606 | ||
607 | @node Asynchronous I/O Signals | |
608 | @subsection Asynchronous I/O Signals | |
609 | ||
610 | The signals listed in this section are used in conjunction with | |
611 | asynchronous I/O facilities. You have to take explicit action by | |
6d52618b | 612 | calling @code{fcntl} to enable a particular file descriptor to generate |
28f540f4 RM |
613 | these signals (@pxref{Interrupt Input}). The default action for these |
614 | signals is to ignore them. | |
615 | ||
616 | @comment signal.h | |
617 | @comment BSD | |
618 | @deftypevr Macro int SIGIO | |
619 | @cindex input available signal | |
620 | @cindex output possible signal | |
621 | This signal is sent when a file descriptor is ready to perform input | |
622 | or output. | |
623 | ||
624 | On most operating systems, terminals and sockets are the only kinds of | |
625 | files that can generate @code{SIGIO}; other kinds, including ordinary | |
626 | files, never generate @code{SIGIO} even if you ask them to. | |
627 | ||
a7a93d50 | 628 | On @gnusystems{} @code{SIGIO} will always be generated properly |
28f540f4 RM |
629 | if you successfully set asynchronous mode with @code{fcntl}. |
630 | @end deftypevr | |
631 | ||
632 | @comment signal.h | |
633 | @comment BSD | |
634 | @deftypevr Macro int SIGURG | |
635 | @cindex urgent data signal | |
636 | This signal is sent when ``urgent'' or out-of-band data arrives on a | |
637 | socket. @xref{Out-of-Band Data}. | |
638 | @end deftypevr | |
639 | ||
640 | @comment signal.h | |
641 | @comment SVID | |
642 | @deftypevr Macro int SIGPOLL | |
643 | This is a System V signal name, more or less similar to @code{SIGIO}. | |
644 | It is defined only for compatibility. | |
645 | @end deftypevr | |
646 | ||
647 | @node Job Control Signals | |
648 | @subsection Job Control Signals | |
649 | @cindex job control signals | |
650 | ||
651 | These signals are used to support job control. If your system | |
652 | doesn't support job control, then these macros are defined but the | |
653 | signals themselves can't be raised or handled. | |
654 | ||
655 | You should generally leave these signals alone unless you really | |
656 | understand how job control works. @xref{Job Control}. | |
657 | ||
658 | @comment signal.h | |
659 | @comment POSIX.1 | |
660 | @deftypevr Macro int SIGCHLD | |
661 | @cindex child process signal | |
662 | This signal is sent to a parent process whenever one of its child | |
663 | processes terminates or stops. | |
664 | ||
665 | The default action for this signal is to ignore it. If you establish a | |
666 | handler for this signal while there are child processes that have | |
667 | terminated but not reported their status via @code{wait} or | |
668 | @code{waitpid} (@pxref{Process Completion}), whether your new handler | |
669 | applies to those processes or not depends on the particular operating | |
670 | system. | |
671 | @end deftypevr | |
672 | ||
673 | @comment signal.h | |
674 | @comment SVID | |
675 | @deftypevr Macro int SIGCLD | |
676 | This is an obsolete name for @code{SIGCHLD}. | |
677 | @end deftypevr | |
678 | ||
679 | @comment signal.h | |
680 | @comment POSIX.1 | |
681 | @deftypevr Macro int SIGCONT | |
682 | @cindex continue signal | |
683 | You can send a @code{SIGCONT} signal to a process to make it continue. | |
684 | This signal is special---it always makes the process continue if it is | |
685 | stopped, before the signal is delivered. The default behavior is to do | |
686 | nothing else. You cannot block this signal. You can set a handler, but | |
687 | @code{SIGCONT} always makes the process continue regardless. | |
688 | ||
689 | Most programs have no reason to handle @code{SIGCONT}; they simply | |
690 | resume execution without realizing they were ever stopped. You can use | |
691 | a handler for @code{SIGCONT} to make a program do something special when | |
692 | it is stopped and continued---for example, to reprint a prompt when it | |
693 | is suspended while waiting for input. | |
694 | @end deftypevr | |
695 | ||
696 | @comment signal.h | |
697 | @comment POSIX.1 | |
698 | @deftypevr Macro int SIGSTOP | |
699 | The @code{SIGSTOP} signal stops the process. It cannot be handled, | |
700 | ignored, or blocked. | |
701 | @end deftypevr | |
702 | @cindex stop signal | |
703 | ||
704 | @comment signal.h | |
705 | @comment POSIX.1 | |
706 | @deftypevr Macro int SIGTSTP | |
707 | The @code{SIGTSTP} signal is an interactive stop signal. Unlike | |
f65fd747 | 708 | @code{SIGSTOP}, this signal can be handled and ignored. |
28f540f4 RM |
709 | |
710 | Your program should handle this signal if you have a special need to | |
711 | leave files or system tables in a secure state when a process is | |
712 | stopped. For example, programs that turn off echoing should handle | |
713 | @code{SIGTSTP} so they can turn echoing back on before stopping. | |
714 | ||
715 | This signal is generated when the user types the SUSP character | |
716 | (normally @kbd{C-z}). For more information about terminal driver | |
717 | support, see @ref{Special Characters}. | |
718 | @end deftypevr | |
719 | @cindex interactive stop signal | |
720 | ||
721 | @comment signal.h | |
722 | @comment POSIX.1 | |
723 | @deftypevr Macro int SIGTTIN | |
3081378b | 724 | A process cannot read from the user's terminal while it is running |
28f540f4 RM |
725 | as a background job. When any process in a background job tries to |
726 | read from the terminal, all of the processes in the job are sent a | |
727 | @code{SIGTTIN} signal. The default action for this signal is to | |
728 | stop the process. For more information about how this interacts with | |
729 | the terminal driver, see @ref{Access to the Terminal}. | |
730 | @end deftypevr | |
731 | @cindex terminal input signal | |
732 | ||
733 | @comment signal.h | |
734 | @comment POSIX.1 | |
735 | @deftypevr Macro int SIGTTOU | |
736 | This is similar to @code{SIGTTIN}, but is generated when a process in a | |
737 | background job attempts to write to the terminal or set its modes. | |
738 | Again, the default action is to stop the process. @code{SIGTTOU} is | |
739 | only generated for an attempt to write to the terminal if the | |
740 | @code{TOSTOP} output mode is set; @pxref{Output Modes}. | |
741 | @end deftypevr | |
742 | @cindex terminal output signal | |
743 | ||
744 | While a process is stopped, no more signals can be delivered to it until | |
745 | it is continued, except @code{SIGKILL} signals and (obviously) | |
746 | @code{SIGCONT} signals. The signals are marked as pending, but not | |
747 | delivered until the process is continued. The @code{SIGKILL} signal | |
748 | always causes termination of the process and can't be blocked, handled | |
749 | or ignored. You can ignore @code{SIGCONT}, but it always causes the | |
750 | process to be continued anyway if it is stopped. Sending a | |
751 | @code{SIGCONT} signal to a process causes any pending stop signals for | |
752 | that process to be discarded. Likewise, any pending @code{SIGCONT} | |
753 | signals for a process are discarded when it receives a stop signal. | |
754 | ||
755 | When a process in an orphaned process group (@pxref{Orphaned Process | |
756 | Groups}) receives a @code{SIGTSTP}, @code{SIGTTIN}, or @code{SIGTTOU} | |
757 | signal and does not handle it, the process does not stop. Stopping the | |
758 | process would probably not be very useful, since there is no shell | |
759 | program that will notice it stop and allow the user to continue it. | |
760 | What happens instead depends on the operating system you are using. | |
761 | Some systems may do nothing; others may deliver another signal instead, | |
a7a93d50 | 762 | such as @code{SIGKILL} or @code{SIGHUP}. On @gnuhurdsystems{}, the process |
28f540f4 RM |
763 | dies with @code{SIGKILL}; this avoids the problem of many stopped, |
764 | orphaned processes lying around the system. | |
765 | ||
766 | @ignore | |
a7a93d50 | 767 | On @gnuhurdsystems{}, it is possible to reattach to the orphaned process |
28f540f4 | 768 | group and continue it, so stop signals do stop the process as usual on |
a7a93d50 | 769 | @gnuhurdsystems{} unless you have requested POSIX compatibility ``till it |
28f540f4 RM |
770 | hurts.'' |
771 | @end ignore | |
772 | ||
773 | @node Operation Error Signals | |
774 | @subsection Operation Error Signals | |
775 | ||
776 | These signals are used to report various errors generated by an | |
777 | operation done by the program. They do not necessarily indicate a | |
778 | programming error in the program, but an error that prevents an | |
779 | operating system call from completing. The default action for all of | |
780 | them is to cause the process to terminate. | |
781 | ||
782 | @comment signal.h | |
783 | @comment POSIX.1 | |
784 | @deftypevr Macro int SIGPIPE | |
785 | @cindex pipe signal | |
786 | @cindex broken pipe signal | |
787 | Broken pipe. If you use pipes or FIFOs, you have to design your | |
788 | application so that one process opens the pipe for reading before | |
789 | another starts writing. If the reading process never starts, or | |
790 | terminates unexpectedly, writing to the pipe or FIFO raises a | |
791 | @code{SIGPIPE} signal. If @code{SIGPIPE} is blocked, handled or | |
792 | ignored, the offending call fails with @code{EPIPE} instead. | |
793 | ||
794 | Pipes and FIFO special files are discussed in more detail in @ref{Pipes | |
795 | and FIFOs}. | |
796 | ||
797 | Another cause of @code{SIGPIPE} is when you try to output to a socket | |
798 | that isn't connected. @xref{Sending Data}. | |
799 | @end deftypevr | |
800 | ||
801 | @comment signal.h | |
802 | @comment GNU | |
803 | @deftypevr Macro int SIGLOST | |
804 | @cindex lost resource signal | |
805 | Resource lost. This signal is generated when you have an advisory lock | |
806 | on an NFS file, and the NFS server reboots and forgets about your lock. | |
807 | ||
a7a93d50 | 808 | On @gnuhurdsystems{}, @code{SIGLOST} is generated when any server program |
28f540f4 RM |
809 | dies unexpectedly. It is usually fine to ignore the signal; whatever |
810 | call was made to the server that died just returns an error. | |
811 | @end deftypevr | |
812 | ||
813 | @comment signal.h | |
814 | @comment BSD | |
815 | @deftypevr Macro int SIGXCPU | |
816 | CPU time limit exceeded. This signal is generated when the process | |
817 | exceeds its soft resource limit on CPU time. @xref{Limits on Resources}. | |
818 | @end deftypevr | |
819 | ||
820 | @comment signal.h | |
821 | @comment BSD | |
822 | @deftypevr Macro int SIGXFSZ | |
823 | File size limit exceeded. This signal is generated when the process | |
824 | attempts to extend a file so it exceeds the process's soft resource | |
825 | limit on file size. @xref{Limits on Resources}. | |
826 | @end deftypevr | |
827 | ||
828 | @node Miscellaneous Signals | |
829 | @subsection Miscellaneous Signals | |
830 | ||
831 | These signals are used for various other purposes. In general, they | |
832 | will not affect your program unless it explicitly uses them for something. | |
833 | ||
834 | @comment signal.h | |
835 | @comment POSIX.1 | |
836 | @deftypevr Macro int SIGUSR1 | |
28f540f4 RM |
837 | @comment signal.h |
838 | @comment POSIX.1 | |
779ae82e | 839 | @deftypevrx Macro int SIGUSR2 |
28f540f4 RM |
840 | @cindex user signals |
841 | The @code{SIGUSR1} and @code{SIGUSR2} signals are set aside for you to | |
842 | use any way you want. They're useful for simple interprocess | |
843 | communication, if you write a signal handler for them in the program | |
844 | that receives the signal. | |
845 | ||
846 | There is an example showing the use of @code{SIGUSR1} and @code{SIGUSR2} | |
847 | in @ref{Signaling Another Process}. | |
848 | ||
849 | The default action is to terminate the process. | |
850 | @end deftypevr | |
851 | ||
852 | @comment signal.h | |
853 | @comment BSD | |
854 | @deftypevr Macro int SIGWINCH | |
855 | Window size change. This is generated on some systems (including GNU) | |
856 | when the terminal driver's record of the number of rows and columns on | |
857 | the screen is changed. The default action is to ignore it. | |
858 | ||
859 | If a program does full-screen display, it should handle @code{SIGWINCH}. | |
860 | When the signal arrives, it should fetch the new screen size and | |
861 | reformat its display accordingly. | |
862 | @end deftypevr | |
863 | ||
864 | @comment signal.h | |
865 | @comment BSD | |
866 | @deftypevr Macro int SIGINFO | |
a7a93d50 | 867 | Information request. On 4.4 BSD and @gnuhurdsystems{}, this signal is sent |
28f540f4 RM |
868 | to all the processes in the foreground process group of the controlling |
869 | terminal when the user types the STATUS character in canonical mode; | |
870 | @pxref{Signal Characters}. | |
871 | ||
872 | If the process is the leader of the process group, the default action is | |
873 | to print some status information about the system and what the process | |
874 | is doing. Otherwise the default is to do nothing. | |
875 | @end deftypevr | |
876 | ||
877 | @node Signal Messages | |
878 | @subsection Signal Messages | |
879 | @cindex signal messages | |
880 | ||
881 | We mentioned above that the shell prints a message describing the signal | |
882 | that terminated a child process. The clean way to print a message | |
883 | describing a signal is to use the functions @code{strsignal} and | |
884 | @code{psignal}. These functions use a signal number to specify which | |
885 | kind of signal to describe. The signal number may come from the | |
886 | termination status of a child process (@pxref{Process Completion}) or it | |
887 | may come from a signal handler in the same process. | |
888 | ||
889 | @comment string.h | |
890 | @comment GNU | |
891 | @deftypefun {char *} strsignal (int @var{signum}) | |
892 | This function returns a pointer to a statically-allocated string | |
893 | containing a message describing the signal @var{signum}. You | |
894 | should not modify the contents of this string; and, since it can be | |
895 | rewritten on subsequent calls, you should save a copy of it if you need | |
896 | to reference it later. | |
897 | ||
898 | @pindex string.h | |
899 | This function is a GNU extension, declared in the header file | |
900 | @file{string.h}. | |
901 | @end deftypefun | |
902 | ||
903 | @comment signal.h | |
904 | @comment BSD | |
905 | @deftypefun void psignal (int @var{signum}, const char *@var{message}) | |
906 | This function prints a message describing the signal @var{signum} to the | |
907 | standard error output stream @code{stderr}; see @ref{Standard Streams}. | |
908 | ||
909 | If you call @code{psignal} with a @var{message} that is either a null | |
f65fd747 | 910 | pointer or an empty string, @code{psignal} just prints the message |
28f540f4 RM |
911 | corresponding to @var{signum}, adding a trailing newline. |
912 | ||
913 | If you supply a non-null @var{message} argument, then @code{psignal} | |
f65fd747 | 914 | prefixes its output with this string. It adds a colon and a space |
28f540f4 RM |
915 | character to separate the @var{message} from the string corresponding |
916 | to @var{signum}. | |
917 | ||
918 | @pindex stdio.h | |
919 | This function is a BSD feature, declared in the header file @file{signal.h}. | |
920 | @end deftypefun | |
921 | ||
922 | @vindex sys_siglist | |
923 | There is also an array @code{sys_siglist} which contains the messages | |
924 | for the various signal codes. This array exists on BSD systems, unlike | |
925 | @code{strsignal}. | |
926 | ||
927 | @node Signal Actions | |
928 | @section Specifying Signal Actions | |
929 | @cindex signal actions | |
930 | @cindex establishing a handler | |
931 | ||
932 | The simplest way to change the action for a signal is to use the | |
933 | @code{signal} function. You can specify a built-in action (such as to | |
934 | ignore the signal), or you can @dfn{establish a handler}. | |
935 | ||
1f77f049 | 936 | @Theglibc{} also implements the more versatile @code{sigaction} |
28f540f4 RM |
937 | facility. This section describes both facilities and gives suggestions |
938 | on which to use when. | |
939 | ||
940 | @menu | |
941 | * Basic Signal Handling:: The simple @code{signal} function. | |
942 | * Advanced Signal Handling:: The more powerful @code{sigaction} function. | |
943 | * Signal and Sigaction:: How those two functions interact. | |
944 | * Sigaction Function Example:: An example of using the sigaction function. | |
945 | * Flags for Sigaction:: Specifying options for signal handling. | |
946 | * Initial Signal Actions:: How programs inherit signal actions. | |
947 | @end menu | |
948 | ||
949 | @node Basic Signal Handling | |
950 | @subsection Basic Signal Handling | |
951 | @cindex @code{signal} function | |
952 | ||
953 | The @code{signal} function provides a simple interface for establishing | |
954 | an action for a particular signal. The function and associated macros | |
955 | are declared in the header file @file{signal.h}. | |
956 | @pindex signal.h | |
957 | ||
958 | @comment signal.h | |
959 | @comment GNU | |
960 | @deftp {Data Type} sighandler_t | |
961 | This is the type of signal handler functions. Signal handlers take one | |
962 | integer argument specifying the signal number, and have return type | |
963 | @code{void}. So, you should define handler functions like this: | |
964 | ||
965 | @smallexample | |
966 | void @var{handler} (int @code{signum}) @{ @dots{} @} | |
967 | @end smallexample | |
968 | ||
969 | The name @code{sighandler_t} for this data type is a GNU extension. | |
970 | @end deftp | |
971 | ||
972 | @comment signal.h | |
f65fd747 | 973 | @comment ISO |
28f540f4 RM |
974 | @deftypefun sighandler_t signal (int @var{signum}, sighandler_t @var{action}) |
975 | The @code{signal} function establishes @var{action} as the action for | |
976 | the signal @var{signum}. | |
977 | ||
978 | The first argument, @var{signum}, identifies the signal whose behavior | |
979 | you want to control, and should be a signal number. The proper way to | |
980 | specify a signal number is with one of the symbolic signal names | |
8b7fb588 | 981 | (@pxref{Standard Signals})---don't use an explicit number, because |
28f540f4 RM |
982 | the numerical code for a given kind of signal may vary from operating |
983 | system to operating system. | |
984 | ||
985 | The second argument, @var{action}, specifies the action to use for the | |
986 | signal @var{signum}. This can be one of the following: | |
987 | ||
988 | @table @code | |
989 | @item SIG_DFL | |
990 | @vindex SIG_DFL | |
991 | @cindex default action for a signal | |
992 | @code{SIG_DFL} specifies the default action for the particular signal. | |
993 | The default actions for various kinds of signals are stated in | |
994 | @ref{Standard Signals}. | |
995 | ||
996 | @item SIG_IGN | |
997 | @vindex SIG_IGN | |
998 | @cindex ignore action for a signal | |
999 | @code{SIG_IGN} specifies that the signal should be ignored. | |
1000 | ||
1001 | Your program generally should not ignore signals that represent serious | |
1002 | events or that are normally used to request termination. You cannot | |
1003 | ignore the @code{SIGKILL} or @code{SIGSTOP} signals at all. You can | |
1004 | ignore program error signals like @code{SIGSEGV}, but ignoring the error | |
1005 | won't enable the program to continue executing meaningfully. Ignoring | |
1006 | user requests such as @code{SIGINT}, @code{SIGQUIT}, and @code{SIGTSTP} | |
1007 | is unfriendly. | |
1008 | ||
1009 | When you do not wish signals to be delivered during a certain part of | |
1010 | the program, the thing to do is to block them, not ignore them. | |
1011 | @xref{Blocking Signals}. | |
1012 | ||
1013 | @item @var{handler} | |
1014 | Supply the address of a handler function in your program, to specify | |
1015 | running this handler as the way to deliver the signal. | |
1016 | ||
1017 | For more information about defining signal handler functions, | |
1018 | see @ref{Defining Handlers}. | |
1019 | @end table | |
1020 | ||
1021 | If you set the action for a signal to @code{SIG_IGN}, or if you set it | |
1022 | to @code{SIG_DFL} and the default action is to ignore that signal, then | |
1023 | any pending signals of that type are discarded (even if they are | |
1024 | blocked). Discarding the pending signals means that they will never be | |
1025 | delivered, not even if you subsequently specify another action and | |
1026 | unblock this kind of signal. | |
1027 | ||
1028 | The @code{signal} function returns the action that was previously in | |
1029 | effect for the specified @var{signum}. You can save this value and | |
1030 | restore it later by calling @code{signal} again. | |
1031 | ||
1032 | If @code{signal} can't honor the request, it returns @code{SIG_ERR} | |
1033 | instead. The following @code{errno} error conditions are defined for | |
1034 | this function: | |
1035 | ||
1036 | @table @code | |
1037 | @item EINVAL | |
1038 | You specified an invalid @var{signum}; or you tried to ignore or provide | |
1039 | a handler for @code{SIGKILL} or @code{SIGSTOP}. | |
1040 | @end table | |
1041 | @end deftypefun | |
1042 | ||
bafb8ee9 UD |
1043 | @strong{Compatibility Note:} A problem encountered when working with the |
1044 | @code{signal} function is that it has different semantics on BSD and | |
1045 | SVID systems. The difference is that on SVID systems the signal handler | |
1046 | is deinstalled after signal delivery. On BSD systems the | |
1f77f049 | 1047 | handler must be explicitly deinstalled. In @theglibc{} we use the |
ceb2d9aa UD |
1048 | BSD version by default. To use the SVID version you can either use the |
1049 | function @code{sysv_signal} (see below) or use the @code{_XOPEN_SOURCE} | |
bafb8ee9 UD |
1050 | feature select macro (@pxref{Feature Test Macros}). In general, use of these |
1051 | functions should be avoided because of compatibility problems. It | |
ceb2d9aa UD |
1052 | is better to use @code{sigaction} if it is available since the results |
1053 | are much more reliable. | |
1054 | ||
28f540f4 RM |
1055 | Here is a simple example of setting up a handler to delete temporary |
1056 | files when certain fatal signals happen: | |
1057 | ||
1058 | @smallexample | |
1059 | #include <signal.h> | |
1060 | ||
1061 | void | |
1062 | termination_handler (int signum) | |
1063 | @{ | |
1064 | struct temp_file *p; | |
1065 | ||
1066 | for (p = temp_file_list; p; p = p->next) | |
1067 | unlink (p->name); | |
1068 | @} | |
1069 | ||
1070 | int | |
1071 | main (void) | |
1072 | @{ | |
1073 | @dots{} | |
1074 | if (signal (SIGINT, termination_handler) == SIG_IGN) | |
1075 | signal (SIGINT, SIG_IGN); | |
1076 | if (signal (SIGHUP, termination_handler) == SIG_IGN) | |
1077 | signal (SIGHUP, SIG_IGN); | |
1078 | if (signal (SIGTERM, termination_handler) == SIG_IGN) | |
1079 | signal (SIGTERM, SIG_IGN); | |
1080 | @dots{} | |
1081 | @} | |
1082 | @end smallexample | |
1083 | ||
1084 | @noindent | |
bafb8ee9 | 1085 | Note that if a given signal was previously set to be ignored, this code |
28f540f4 RM |
1086 | avoids altering that setting. This is because non-job-control shells |
1087 | often ignore certain signals when starting children, and it is important | |
1088 | for the children to respect this. | |
1089 | ||
1090 | We do not handle @code{SIGQUIT} or the program error signals in this | |
1091 | example because these are designed to provide information for debugging | |
1092 | (a core dump), and the temporary files may give useful information. | |
1093 | ||
ceb2d9aa UD |
1094 | @comment signal.h |
1095 | @comment GNU | |
1096 | @deftypefun sighandler_t sysv_signal (int @var{signum}, sighandler_t @var{action}) | |
0bc93a2f | 1097 | The @code{sysv_signal} implements the behavior of the standard |
ceb2d9aa UD |
1098 | @code{signal} function as found on SVID systems. The difference to BSD |
1099 | systems is that the handler is deinstalled after a delivery of a signal. | |
1100 | ||
1101 | @strong{Compatibility Note:} As said above for @code{signal}, this | |
1102 | function should be avoided when possible. @code{sigaction} is the | |
1103 | preferred method. | |
1104 | @end deftypefun | |
1105 | ||
28f540f4 RM |
1106 | @comment signal.h |
1107 | @comment SVID | |
1108 | @deftypefun sighandler_t ssignal (int @var{signum}, sighandler_t @var{action}) | |
1109 | The @code{ssignal} function does the same thing as @code{signal}; it is | |
1110 | provided only for compatibility with SVID. | |
1111 | @end deftypefun | |
1112 | ||
1113 | @comment signal.h | |
f65fd747 | 1114 | @comment ISO |
28f540f4 RM |
1115 | @deftypevr Macro sighandler_t SIG_ERR |
1116 | The value of this macro is used as the return value from @code{signal} | |
1117 | to indicate an error. | |
1118 | @end deftypevr | |
1119 | ||
1120 | @ignore | |
1121 | @comment RMS says that ``we don't do this''. | |
1122 | Implementations might define additional macros for built-in signal | |
1123 | actions that are suitable as a @var{action} argument to @code{signal}, | |
1124 | besides @code{SIG_IGN} and @code{SIG_DFL}. Identifiers whose names | |
1125 | begin with @samp{SIG_} followed by an uppercase letter are reserved for | |
1126 | this purpose. | |
1127 | @end ignore | |
1128 | ||
1129 | ||
1130 | @node Advanced Signal Handling | |
1131 | @subsection Advanced Signal Handling | |
1132 | @cindex @code{sigaction} function | |
1133 | ||
1134 | The @code{sigaction} function has the same basic effect as | |
1135 | @code{signal}: to specify how a signal should be handled by the process. | |
1136 | However, @code{sigaction} offers more control, at the expense of more | |
1137 | complexity. In particular, @code{sigaction} allows you to specify | |
1138 | additional flags to control when the signal is generated and how the | |
1139 | handler is invoked. | |
1140 | ||
1141 | The @code{sigaction} function is declared in @file{signal.h}. | |
1142 | @pindex signal.h | |
1143 | ||
1144 | @comment signal.h | |
1145 | @comment POSIX.1 | |
1146 | @deftp {Data Type} {struct sigaction} | |
1147 | Structures of type @code{struct sigaction} are used in the | |
1148 | @code{sigaction} function to specify all the information about how to | |
1149 | handle a particular signal. This structure contains at least the | |
1150 | following members: | |
1151 | ||
1152 | @table @code | |
1153 | @item sighandler_t sa_handler | |
1154 | This is used in the same way as the @var{action} argument to the | |
1155 | @code{signal} function. The value can be @code{SIG_DFL}, | |
1156 | @code{SIG_IGN}, or a function pointer. @xref{Basic Signal Handling}. | |
1157 | ||
1158 | @item sigset_t sa_mask | |
1159 | This specifies a set of signals to be blocked while the handler runs. | |
1160 | Blocking is explained in @ref{Blocking for Handler}. Note that the | |
1161 | signal that was delivered is automatically blocked by default before its | |
1162 | handler is started; this is true regardless of the value in | |
1163 | @code{sa_mask}. If you want that signal not to be blocked within its | |
1164 | handler, you must write code in the handler to unblock it. | |
1165 | ||
1166 | @item int sa_flags | |
f65fd747 | 1167 | This specifies various flags which can affect the behavior of |
28f540f4 RM |
1168 | the signal. These are described in more detail in @ref{Flags for Sigaction}. |
1169 | @end table | |
1170 | @end deftp | |
1171 | ||
1172 | @comment signal.h | |
1173 | @comment POSIX.1 | |
eacde9d0 | 1174 | @deftypefun int sigaction (int @var{signum}, const struct sigaction *restrict @var{action}, struct sigaction *restrict @var{old-action}) |
28f540f4 RM |
1175 | The @var{action} argument is used to set up a new action for the signal |
1176 | @var{signum}, while the @var{old-action} argument is used to return | |
1177 | information about the action previously associated with this symbol. | |
1178 | (In other words, @var{old-action} has the same purpose as the | |
1179 | @code{signal} function's return value---you can check to see what the | |
1180 | old action in effect for the signal was, and restore it later if you | |
1181 | want.) | |
1182 | ||
1183 | Either @var{action} or @var{old-action} can be a null pointer. If | |
1184 | @var{old-action} is a null pointer, this simply suppresses the return | |
1185 | of information about the old action. If @var{action} is a null pointer, | |
1186 | the action associated with the signal @var{signum} is unchanged; this | |
1187 | allows you to inquire about how a signal is being handled without changing | |
1188 | that handling. | |
1189 | ||
1190 | The return value from @code{sigaction} is zero if it succeeds, and | |
1191 | @code{-1} on failure. The following @code{errno} error conditions are | |
1192 | defined for this function: | |
1193 | ||
1194 | @table @code | |
1195 | @item EINVAL | |
1196 | The @var{signum} argument is not valid, or you are trying to | |
1197 | trap or ignore @code{SIGKILL} or @code{SIGSTOP}. | |
1198 | @end table | |
1199 | @end deftypefun | |
1200 | ||
1201 | @node Signal and Sigaction | |
1202 | @subsection Interaction of @code{signal} and @code{sigaction} | |
1203 | ||
1204 | It's possible to use both the @code{signal} and @code{sigaction} | |
1205 | functions within a single program, but you have to be careful because | |
1206 | they can interact in slightly strange ways. | |
1207 | ||
1208 | The @code{sigaction} function specifies more information than the | |
1209 | @code{signal} function, so the return value from @code{signal} cannot | |
1210 | express the full range of @code{sigaction} possibilities. Therefore, if | |
1211 | you use @code{signal} to save and later reestablish an action, it may | |
1212 | not be able to reestablish properly a handler that was established with | |
1213 | @code{sigaction}. | |
1214 | ||
1215 | To avoid having problems as a result, always use @code{sigaction} to | |
1216 | save and restore a handler if your program uses @code{sigaction} at all. | |
1217 | Since @code{sigaction} is more general, it can properly save and | |
1218 | reestablish any action, regardless of whether it was established | |
1219 | originally with @code{signal} or @code{sigaction}. | |
1220 | ||
1221 | On some systems if you establish an action with @code{signal} and then | |
1222 | examine it with @code{sigaction}, the handler address that you get may | |
1223 | not be the same as what you specified with @code{signal}. It may not | |
1224 | even be suitable for use as an action argument with @code{signal}. But | |
1225 | you can rely on using it as an argument to @code{sigaction}. This | |
a7a93d50 | 1226 | problem never happens on @gnusystems{}. |
28f540f4 RM |
1227 | |
1228 | So, you're better off using one or the other of the mechanisms | |
f65fd747 | 1229 | consistently within a single program. |
28f540f4 RM |
1230 | |
1231 | @strong{Portability Note:} The basic @code{signal} function is a feature | |
f65fd747 | 1232 | of @w{ISO C}, while @code{sigaction} is part of the POSIX.1 standard. If |
28f540f4 RM |
1233 | you are concerned about portability to non-POSIX systems, then you |
1234 | should use the @code{signal} function instead. | |
1235 | ||
1236 | @node Sigaction Function Example | |
1237 | @subsection @code{sigaction} Function Example | |
1238 | ||
1239 | In @ref{Basic Signal Handling}, we gave an example of establishing a | |
1240 | simple handler for termination signals using @code{signal}. Here is an | |
1241 | equivalent example using @code{sigaction}: | |
1242 | ||
1243 | @smallexample | |
1244 | #include <signal.h> | |
1245 | ||
1246 | void | |
1247 | termination_handler (int signum) | |
1248 | @{ | |
1249 | struct temp_file *p; | |
1250 | ||
1251 | for (p = temp_file_list; p; p = p->next) | |
1252 | unlink (p->name); | |
1253 | @} | |
1254 | ||
1255 | int | |
1256 | main (void) | |
1257 | @{ | |
1258 | @dots{} | |
1259 | struct sigaction new_action, old_action; | |
1260 | ||
1261 | /* @r{Set up the structure to specify the new action.} */ | |
1262 | new_action.sa_handler = termination_handler; | |
1263 | sigemptyset (&new_action.sa_mask); | |
1264 | new_action.sa_flags = 0; | |
1265 | ||
1266 | sigaction (SIGINT, NULL, &old_action); | |
1267 | if (old_action.sa_handler != SIG_IGN) | |
1268 | sigaction (SIGINT, &new_action, NULL); | |
1269 | sigaction (SIGHUP, NULL, &old_action); | |
1270 | if (old_action.sa_handler != SIG_IGN) | |
1271 | sigaction (SIGHUP, &new_action, NULL); | |
1272 | sigaction (SIGTERM, NULL, &old_action); | |
1273 | if (old_action.sa_handler != SIG_IGN) | |
1274 | sigaction (SIGTERM, &new_action, NULL); | |
1275 | @dots{} | |
1276 | @} | |
1277 | @end smallexample | |
1278 | ||
1279 | The program just loads the @code{new_action} structure with the desired | |
1280 | parameters and passes it in the @code{sigaction} call. The usage of | |
1281 | @code{sigemptyset} is described later; see @ref{Blocking Signals}. | |
1282 | ||
1283 | As in the example using @code{signal}, we avoid handling signals | |
1284 | previously set to be ignored. Here we can avoid altering the signal | |
1285 | handler even momentarily, by using the feature of @code{sigaction} that | |
1286 | lets us examine the current action without specifying a new one. | |
1287 | ||
1288 | Here is another example. It retrieves information about the current | |
1289 | action for @code{SIGINT} without changing that action. | |
1290 | ||
1291 | @smallexample | |
1292 | struct sigaction query_action; | |
1293 | ||
1294 | if (sigaction (SIGINT, NULL, &query_action) < 0) | |
f65fd747 | 1295 | /* @r{@code{sigaction} returns -1 in case of error.} */ |
28f540f4 RM |
1296 | else if (query_action.sa_handler == SIG_DFL) |
1297 | /* @r{@code{SIGINT} is handled in the default, fatal manner.} */ | |
1298 | else if (query_action.sa_handler == SIG_IGN) | |
1299 | /* @r{@code{SIGINT} is ignored.} */ | |
1300 | else | |
1301 | /* @r{A programmer-defined signal handler is in effect.} */ | |
1302 | @end smallexample | |
1303 | ||
1304 | @node Flags for Sigaction | |
1305 | @subsection Flags for @code{sigaction} | |
1306 | @cindex signal flags | |
1307 | @cindex flags for @code{sigaction} | |
1308 | @cindex @code{sigaction} flags | |
1309 | ||
1310 | The @code{sa_flags} member of the @code{sigaction} structure is a | |
1311 | catch-all for special features. Most of the time, @code{SA_RESTART} is | |
1312 | a good value to use for this field. | |
1313 | ||
1314 | The value of @code{sa_flags} is interpreted as a bit mask. Thus, you | |
1315 | should choose the flags you want to set, @sc{or} those flags together, | |
1316 | and store the result in the @code{sa_flags} member of your | |
1317 | @code{sigaction} structure. | |
1318 | ||
1319 | Each signal number has its own set of flags. Each call to | |
1320 | @code{sigaction} affects one particular signal number, and the flags | |
1321 | that you specify apply only to that particular signal. | |
1322 | ||
1f77f049 | 1323 | In @theglibc{}, establishing a handler with @code{signal} sets all |
28f540f4 RM |
1324 | the flags to zero except for @code{SA_RESTART}, whose value depends on |
1325 | the settings you have made with @code{siginterrupt}. @xref{Interrupted | |
1326 | Primitives}, to see what this is about. | |
1327 | ||
1328 | @pindex signal.h | |
1329 | These macros are defined in the header file @file{signal.h}. | |
1330 | ||
1331 | @comment signal.h | |
1332 | @comment POSIX.1 | |
1333 | @deftypevr Macro int SA_NOCLDSTOP | |
1334 | This flag is meaningful only for the @code{SIGCHLD} signal. When the | |
1335 | flag is set, the system delivers the signal for a terminated child | |
1336 | process but not for one that is stopped. By default, @code{SIGCHLD} is | |
1337 | delivered for both terminated children and stopped children. | |
1338 | ||
1339 | Setting this flag for a signal other than @code{SIGCHLD} has no effect. | |
1340 | @end deftypevr | |
1341 | ||
1342 | @comment signal.h | |
1343 | @comment BSD | |
1344 | @deftypevr Macro int SA_ONSTACK | |
1345 | If this flag is set for a particular signal number, the system uses the | |
1346 | signal stack when delivering that kind of signal. @xref{Signal Stack}. | |
1347 | If a signal with this flag arrives and you have not set a signal stack, | |
1348 | the system terminates the program with @code{SIGILL}. | |
1349 | @end deftypevr | |
1350 | ||
1351 | @comment signal.h | |
1352 | @comment BSD | |
1353 | @deftypevr Macro int SA_RESTART | |
1354 | This flag controls what happens when a signal is delivered during | |
1355 | certain primitives (such as @code{open}, @code{read} or @code{write}), | |
1356 | and the signal handler returns normally. There are two alternatives: | |
1357 | the library function can resume, or it can return failure with error | |
1358 | code @code{EINTR}. | |
1359 | ||
1360 | The choice is controlled by the @code{SA_RESTART} flag for the | |
1361 | particular kind of signal that was delivered. If the flag is set, | |
1362 | returning from a handler resumes the library function. If the flag is | |
1363 | clear, returning from a handler makes the function fail. | |
1364 | @xref{Interrupted Primitives}. | |
1365 | @end deftypevr | |
1366 | ||
1367 | @node Initial Signal Actions | |
1368 | @subsection Initial Signal Actions | |
1369 | @cindex initial signal actions | |
1370 | ||
1371 | When a new process is created (@pxref{Creating a Process}), it inherits | |
1372 | handling of signals from its parent process. However, when you load a | |
1373 | new process image using the @code{exec} function (@pxref{Executing a | |
1374 | File}), any signals that you've defined your own handlers for revert to | |
1375 | their @code{SIG_DFL} handling. (If you think about it a little, this | |
1376 | makes sense; the handler functions from the old program are specific to | |
1377 | that program, and aren't even present in the address space of the new | |
1378 | program image.) Of course, the new program can establish its own | |
1379 | handlers. | |
1380 | ||
1381 | When a program is run by a shell, the shell normally sets the initial | |
1382 | actions for the child process to @code{SIG_DFL} or @code{SIG_IGN}, as | |
1383 | appropriate. It's a good idea to check to make sure that the shell has | |
1384 | not set up an initial action of @code{SIG_IGN} before you establish your | |
1385 | own signal handlers. | |
1386 | ||
1387 | Here is an example of how to establish a handler for @code{SIGHUP}, but | |
1388 | not if @code{SIGHUP} is currently ignored: | |
1389 | ||
1390 | @smallexample | |
1391 | @group | |
1392 | @dots{} | |
1393 | struct sigaction temp; | |
1394 | ||
1395 | sigaction (SIGHUP, NULL, &temp); | |
1396 | ||
1397 | if (temp.sa_handler != SIG_IGN) | |
1398 | @{ | |
1399 | temp.sa_handler = handle_sighup; | |
1400 | sigemptyset (&temp.sa_mask); | |
1401 | sigaction (SIGHUP, &temp, NULL); | |
1402 | @} | |
1403 | @end group | |
1404 | @end smallexample | |
1405 | ||
1406 | @node Defining Handlers | |
1407 | @section Defining Signal Handlers | |
1408 | @cindex signal handler function | |
1409 | ||
1410 | This section describes how to write a signal handler function that can | |
1411 | be established with the @code{signal} or @code{sigaction} functions. | |
1412 | ||
1413 | A signal handler is just a function that you compile together with the | |
1414 | rest of the program. Instead of directly invoking the function, you use | |
1415 | @code{signal} or @code{sigaction} to tell the operating system to call | |
1416 | it when a signal arrives. This is known as @dfn{establishing} the | |
1417 | handler. @xref{Signal Actions}. | |
1418 | ||
1419 | There are two basic strategies you can use in signal handler functions: | |
1420 | ||
1421 | @itemize @bullet | |
1422 | @item | |
1423 | You can have the handler function note that the signal arrived by | |
1424 | tweaking some global data structures, and then return normally. | |
1425 | ||
1426 | @item | |
1427 | You can have the handler function terminate the program or transfer | |
1428 | control to a point where it can recover from the situation that caused | |
1429 | the signal. | |
1430 | @end itemize | |
1431 | ||
1432 | You need to take special care in writing handler functions because they | |
1433 | can be called asynchronously. That is, a handler might be called at any | |
1434 | point in the program, unpredictably. If two signals arrive during a | |
1435 | very short interval, one handler can run within another. This section | |
1436 | describes what your handler should do, and what you should avoid. | |
1437 | ||
1438 | @menu | |
1439 | * Handler Returns:: Handlers that return normally, and what | |
f65fd747 | 1440 | this means. |
28f540f4 RM |
1441 | * Termination in Handler:: How handler functions terminate a program. |
1442 | * Longjmp in Handler:: Nonlocal transfer of control out of a | |
1443 | signal handler. | |
1444 | * Signals in Handler:: What happens when signals arrive while | |
1445 | the handler is already occupied. | |
1446 | * Merged Signals:: When a second signal arrives before the | |
1447 | first is handled. | |
1448 | * Nonreentrancy:: Do not call any functions unless you know they | |
f65fd747 | 1449 | are reentrant with respect to signals. |
28f540f4 | 1450 | * Atomic Data Access:: A single handler can run in the middle of |
f65fd747 | 1451 | reading or writing a single object. |
28f540f4 RM |
1452 | @end menu |
1453 | ||
1454 | @node Handler Returns | |
1455 | @subsection Signal Handlers that Return | |
1456 | ||
1457 | Handlers which return normally are usually used for signals such as | |
1458 | @code{SIGALRM} and the I/O and interprocess communication signals. But | |
1459 | a handler for @code{SIGINT} might also return normally after setting a | |
1460 | flag that tells the program to exit at a convenient time. | |
1461 | ||
1462 | It is not safe to return normally from the handler for a program error | |
1463 | signal, because the behavior of the program when the handler function | |
1464 | returns is not defined after a program error. @xref{Program Error | |
1465 | Signals}. | |
1466 | ||
1467 | Handlers that return normally must modify some global variable in order | |
1468 | to have any effect. Typically, the variable is one that is examined | |
1469 | periodically by the program during normal operation. Its data type | |
1470 | should be @code{sig_atomic_t} for reasons described in @ref{Atomic | |
1471 | Data Access}. | |
1472 | ||
1473 | Here is a simple example of such a program. It executes the body of | |
1474 | the loop until it has noticed that a @code{SIGALRM} signal has arrived. | |
1475 | This technique is useful because it allows the iteration in progress | |
1476 | when the signal arrives to complete before the loop exits. | |
1477 | ||
1478 | @smallexample | |
1479 | @include sigh1.c.texi | |
1480 | @end smallexample | |
1481 | ||
1482 | @node Termination in Handler | |
1483 | @subsection Handlers That Terminate the Process | |
1484 | ||
1485 | Handler functions that terminate the program are typically used to cause | |
1486 | orderly cleanup or recovery from program error signals and interactive | |
1487 | interrupts. | |
1488 | ||
1489 | The cleanest way for a handler to terminate the process is to raise the | |
1490 | same signal that ran the handler in the first place. Here is how to do | |
1491 | this: | |
1492 | ||
1493 | @smallexample | |
1494 | volatile sig_atomic_t fatal_error_in_progress = 0; | |
1495 | ||
1496 | void | |
1497 | fatal_error_signal (int sig) | |
1498 | @{ | |
1499 | @group | |
1500 | /* @r{Since this handler is established for more than one kind of signal, } | |
1501 | @r{it might still get invoked recursively by delivery of some other kind} | |
1502 | @r{of signal. Use a static variable to keep track of that.} */ | |
1503 | if (fatal_error_in_progress) | |
1504 | raise (sig); | |
1505 | fatal_error_in_progress = 1; | |
1506 | @end group | |
1507 | ||
1508 | @group | |
1509 | /* @r{Now do the clean up actions:} | |
1510 | @r{- reset terminal modes} | |
1511 | @r{- kill child processes} | |
1512 | @r{- remove lock files} */ | |
1513 | @dots{} | |
1514 | @end group | |
1515 | ||
1516 | @group | |
57b4b78a UD |
1517 | /* @r{Now reraise the signal. We reactivate the signal's} |
1518 | @r{default handling, which is to terminate the process.} | |
1519 | @r{We could just call @code{exit} or @code{abort},} | |
1520 | @r{but reraising the signal sets the return status} | |
1521 | @r{from the process correctly.} */ | |
1522 | signal (sig, SIG_DFL); | |
28f540f4 RM |
1523 | raise (sig); |
1524 | @} | |
1525 | @end group | |
1526 | @end smallexample | |
1527 | ||
1528 | @node Longjmp in Handler | |
1529 | @subsection Nonlocal Control Transfer in Handlers | |
1530 | @cindex non-local exit, from signal handler | |
1531 | ||
1532 | You can do a nonlocal transfer of control out of a signal handler using | |
1533 | the @code{setjmp} and @code{longjmp} facilities (@pxref{Non-Local | |
1534 | Exits}). | |
1535 | ||
1536 | When the handler does a nonlocal control transfer, the part of the | |
1537 | program that was running will not continue. If this part of the program | |
1538 | was in the middle of updating an important data structure, the data | |
1539 | structure will remain inconsistent. Since the program does not | |
1540 | terminate, the inconsistency is likely to be noticed later on. | |
1541 | ||
1542 | There are two ways to avoid this problem. One is to block the signal | |
1543 | for the parts of the program that update important data structures. | |
1544 | Blocking the signal delays its delivery until it is unblocked, once the | |
1545 | critical updating is finished. @xref{Blocking Signals}. | |
1546 | ||
2056100b RM |
1547 | The other way is to re-initialize the crucial data structures in the |
1548 | signal handler, or to make their values consistent. | |
28f540f4 RM |
1549 | |
1550 | Here is a rather schematic example showing the reinitialization of one | |
1551 | global variable. | |
1552 | ||
1553 | @smallexample | |
1554 | @group | |
1555 | #include <signal.h> | |
1556 | #include <setjmp.h> | |
1557 | ||
1558 | jmp_buf return_to_top_level; | |
1559 | ||
1560 | volatile sig_atomic_t waiting_for_input; | |
1561 | ||
1562 | void | |
1563 | handle_sigint (int signum) | |
1564 | @{ | |
1565 | /* @r{We may have been waiting for input when the signal arrived,} | |
1566 | @r{but we are no longer waiting once we transfer control.} */ | |
1567 | waiting_for_input = 0; | |
1568 | longjmp (return_to_top_level, 1); | |
1569 | @} | |
1570 | @end group | |
1571 | ||
1572 | @group | |
1573 | int | |
1574 | main (void) | |
1575 | @{ | |
1576 | @dots{} | |
1577 | signal (SIGINT, sigint_handler); | |
1578 | @dots{} | |
1579 | while (1) @{ | |
1580 | prepare_for_command (); | |
1581 | if (setjmp (return_to_top_level) == 0) | |
1582 | read_and_execute_command (); | |
1583 | @} | |
1584 | @} | |
1585 | @end group | |
1586 | ||
1587 | @group | |
1588 | /* @r{Imagine this is a subroutine used by various commands.} */ | |
1589 | char * | |
1590 | read_data () | |
1591 | @{ | |
1592 | if (input_from_terminal) @{ | |
1593 | waiting_for_input = 1; | |
1594 | @dots{} | |
1595 | waiting_for_input = 0; | |
f65fd747 | 1596 | @} else @{ |
28f540f4 RM |
1597 | @dots{} |
1598 | @} | |
1599 | @} | |
1600 | @end group | |
1601 | @end smallexample | |
1602 | ||
1603 | ||
1604 | @node Signals in Handler | |
1605 | @subsection Signals Arriving While a Handler Runs | |
1606 | @cindex race conditions, relating to signals | |
1607 | ||
1608 | What happens if another signal arrives while your signal handler | |
1609 | function is running? | |
1610 | ||
1611 | When the handler for a particular signal is invoked, that signal is | |
1612 | automatically blocked until the handler returns. That means that if two | |
1613 | signals of the same kind arrive close together, the second one will be | |
1614 | held until the first has been handled. (The handler can explicitly | |
1615 | unblock the signal using @code{sigprocmask}, if you want to allow more | |
1616 | signals of this type to arrive; see @ref{Process Signal Mask}.) | |
1617 | ||
1618 | However, your handler can still be interrupted by delivery of another | |
1619 | kind of signal. To avoid this, you can use the @code{sa_mask} member of | |
1620 | the action structure passed to @code{sigaction} to explicitly specify | |
1621 | which signals should be blocked while the signal handler runs. These | |
1622 | signals are in addition to the signal for which the handler was invoked, | |
1623 | and any other signals that are normally blocked by the process. | |
1624 | @xref{Blocking for Handler}. | |
1625 | ||
1626 | When the handler returns, the set of blocked signals is restored to the | |
1627 | value it had before the handler ran. So using @code{sigprocmask} inside | |
1628 | the handler only affects what signals can arrive during the execution of | |
1629 | the handler itself, not what signals can arrive once the handler returns. | |
1630 | ||
1631 | @strong{Portability Note:} Always use @code{sigaction} to establish a | |
1632 | handler for a signal that you expect to receive asynchronously, if you | |
1633 | want your program to work properly on System V Unix. On this system, | |
1634 | the handling of a signal whose handler was established with | |
1635 | @code{signal} automatically sets the signal's action back to | |
1636 | @code{SIG_DFL}, and the handler must re-establish itself each time it | |
1637 | runs. This practice, while inconvenient, does work when signals cannot | |
1638 | arrive in succession. However, if another signal can arrive right away, | |
1639 | it may arrive before the handler can re-establish itself. Then the | |
1640 | second signal would receive the default handling, which could terminate | |
1641 | the process. | |
1642 | ||
1643 | @node Merged Signals | |
1644 | @subsection Signals Close Together Merge into One | |
1645 | @cindex handling multiple signals | |
1646 | @cindex successive signals | |
1647 | @cindex merging of signals | |
1648 | ||
1649 | If multiple signals of the same type are delivered to your process | |
1650 | before your signal handler has a chance to be invoked at all, the | |
1651 | handler may only be invoked once, as if only a single signal had | |
1652 | arrived. In effect, the signals merge into one. This situation can | |
1653 | arise when the signal is blocked, or in a multiprocessing environment | |
1654 | where the system is busy running some other processes while the signals | |
1655 | are delivered. This means, for example, that you cannot reliably use a | |
1656 | signal handler to count signals. The only distinction you can reliably | |
1657 | make is whether at least one signal has arrived since a given time in | |
1658 | the past. | |
1659 | ||
1660 | Here is an example of a handler for @code{SIGCHLD} that compensates for | |
f2ea0f5b | 1661 | the fact that the number of signals received may not equal the number of |
04b9968b | 1662 | child processes that generate them. It assumes that the program keeps track |
28f540f4 RM |
1663 | of all the child processes with a chain of structures as follows: |
1664 | ||
1665 | @smallexample | |
1666 | struct process | |
1667 | @{ | |
1668 | struct process *next; | |
1669 | /* @r{The process ID of this child.} */ | |
1670 | int pid; | |
1671 | /* @r{The descriptor of the pipe or pseudo terminal} | |
1672 | @r{on which output comes from this child.} */ | |
1673 | int input_descriptor; | |
1674 | /* @r{Nonzero if this process has stopped or terminated.} */ | |
1675 | sig_atomic_t have_status; | |
1676 | /* @r{The status of this child; 0 if running,} | |
1677 | @r{otherwise a status value from @code{waitpid}.} */ | |
1678 | int status; | |
1679 | @}; | |
1680 | ||
1681 | struct process *process_list; | |
1682 | @end smallexample | |
1683 | ||
1684 | This example also uses a flag to indicate whether signals have arrived | |
1685 | since some time in the past---whenever the program last cleared it to | |
1686 | zero. | |
1687 | ||
1688 | @smallexample | |
1689 | /* @r{Nonzero means some child's status has changed} | |
1690 | @r{so look at @code{process_list} for the details.} */ | |
1691 | int process_status_change; | |
1692 | @end smallexample | |
1693 | ||
1694 | Here is the handler itself: | |
1695 | ||
1696 | @smallexample | |
1697 | void | |
1698 | sigchld_handler (int signo) | |
1699 | @{ | |
1700 | int old_errno = errno; | |
1701 | ||
1702 | while (1) @{ | |
1703 | register int pid; | |
1704 | int w; | |
1705 | struct process *p; | |
1706 | ||
1707 | /* @r{Keep asking for a status until we get a definitive result.} */ | |
f65fd747 | 1708 | do |
28f540f4 RM |
1709 | @{ |
1710 | errno = 0; | |
1711 | pid = waitpid (WAIT_ANY, &w, WNOHANG | WUNTRACED); | |
1712 | @} | |
1713 | while (pid <= 0 && errno == EINTR); | |
1714 | ||
1715 | if (pid <= 0) @{ | |
1716 | /* @r{A real failure means there are no more} | |
1717 | @r{stopped or terminated child processes, so return.} */ | |
1718 | errno = old_errno; | |
1719 | return; | |
1720 | @} | |
1721 | ||
1722 | /* @r{Find the process that signaled us, and record its status.} */ | |
1723 | ||
1724 | for (p = process_list; p; p = p->next) | |
1725 | if (p->pid == pid) @{ | |
1726 | p->status = w; | |
1727 | /* @r{Indicate that the @code{status} field} | |
1728 | @r{has data to look at. We do this only after storing it.} */ | |
1729 | p->have_status = 1; | |
1730 | ||
1731 | /* @r{If process has terminated, stop waiting for its output.} */ | |
1732 | if (WIFSIGNALED (w) || WIFEXITED (w)) | |
1733 | if (p->input_descriptor) | |
1734 | FD_CLR (p->input_descriptor, &input_wait_mask); | |
1735 | ||
1736 | /* @r{The program should check this flag from time to time} | |
1737 | @r{to see if there is any news in @code{process_list}.} */ | |
1738 | ++process_status_change; | |
1739 | @} | |
1740 | ||
1741 | /* @r{Loop around to handle all the processes} | |
1742 | @r{that have something to tell us.} */ | |
1743 | @} | |
1744 | @} | |
1745 | @end smallexample | |
1746 | ||
1747 | Here is the proper way to check the flag @code{process_status_change}: | |
1748 | ||
1749 | @smallexample | |
1750 | if (process_status_change) @{ | |
1751 | struct process *p; | |
1752 | process_status_change = 0; | |
1753 | for (p = process_list; p; p = p->next) | |
1754 | if (p->have_status) @{ | |
1755 | @dots{} @r{Examine @code{p->status}} @dots{} | |
1756 | @} | |
1757 | @} | |
1758 | @end smallexample | |
1759 | ||
1760 | @noindent | |
1761 | It is vital to clear the flag before examining the list; otherwise, if a | |
1762 | signal were delivered just before the clearing of the flag, and after | |
1763 | the appropriate element of the process list had been checked, the status | |
1764 | change would go unnoticed until the next signal arrived to set the flag | |
1765 | again. You could, of course, avoid this problem by blocking the signal | |
1766 | while scanning the list, but it is much more elegant to guarantee | |
1767 | correctness by doing things in the right order. | |
1768 | ||
1769 | The loop which checks process status avoids examining @code{p->status} | |
1770 | until it sees that status has been validly stored. This is to make sure | |
1771 | that the status cannot change in the middle of accessing it. Once | |
1772 | @code{p->have_status} is set, it means that the child process is stopped | |
1773 | or terminated, and in either case, it cannot stop or terminate again | |
1774 | until the program has taken notice. @xref{Atomic Usage}, for more | |
49c091e5 | 1775 | information about coping with interruptions during accesses of a |
28f540f4 RM |
1776 | variable. |
1777 | ||
1778 | Here is another way you can test whether the handler has run since the | |
1779 | last time you checked. This technique uses a counter which is never | |
1780 | changed outside the handler. Instead of clearing the count, the program | |
1781 | remembers the previous value and sees whether it has changed since the | |
1782 | previous check. The advantage of this method is that different parts of | |
1783 | the program can check independently, each part checking whether there | |
1784 | has been a signal since that part last checked. | |
1785 | ||
1786 | @smallexample | |
1787 | sig_atomic_t process_status_change; | |
1788 | ||
1789 | sig_atomic_t last_process_status_change; | |
1790 | ||
1791 | @dots{} | |
1792 | @{ | |
1793 | sig_atomic_t prev = last_process_status_change; | |
1794 | last_process_status_change = process_status_change; | |
1795 | if (last_process_status_change != prev) @{ | |
1796 | struct process *p; | |
1797 | for (p = process_list; p; p = p->next) | |
1798 | if (p->have_status) @{ | |
1799 | @dots{} @r{Examine @code{p->status}} @dots{} | |
1800 | @} | |
1801 | @} | |
1802 | @} | |
1803 | @end smallexample | |
1804 | ||
1805 | @node Nonreentrancy | |
f65fd747 | 1806 | @subsection Signal Handling and Nonreentrant Functions |
28f540f4 RM |
1807 | @cindex restrictions on signal handler functions |
1808 | ||
1809 | Handler functions usually don't do very much. The best practice is to | |
1810 | write a handler that does nothing but set an external variable that the | |
1811 | program checks regularly, and leave all serious work to the program. | |
04b9968b | 1812 | This is best because the handler can be called asynchronously, at |
28f540f4 RM |
1813 | unpredictable times---perhaps in the middle of a primitive function, or |
1814 | even between the beginning and the end of a C operator that requires | |
1815 | multiple instructions. The data structures being manipulated might | |
1816 | therefore be in an inconsistent state when the handler function is | |
1817 | invoked. Even copying one @code{int} variable into another can take two | |
1818 | instructions on most machines. | |
1819 | ||
1820 | This means you have to be very careful about what you do in a signal | |
1821 | handler. | |
1822 | ||
1823 | @itemize @bullet | |
1824 | @item | |
1825 | @cindex @code{volatile} declarations | |
1826 | If your handler needs to access any global variables from your program, | |
1827 | declare those variables @code{volatile}. This tells the compiler that | |
1828 | the value of the variable might change asynchronously, and inhibits | |
1829 | certain optimizations that would be invalidated by such modifications. | |
1830 | ||
1831 | @item | |
1832 | @cindex reentrant functions | |
1833 | If you call a function in the handler, make sure it is @dfn{reentrant} | |
1834 | with respect to signals, or else make sure that the signal cannot | |
1835 | interrupt a call to a related function. | |
1836 | @end itemize | |
1837 | ||
1838 | A function can be non-reentrant if it uses memory that is not on the | |
1839 | stack. | |
1840 | ||
1841 | @itemize @bullet | |
1842 | @item | |
1843 | If a function uses a static variable or a global variable, or a | |
1844 | dynamically-allocated object that it finds for itself, then it is | |
1845 | non-reentrant and any two calls to the function can interfere. | |
1846 | ||
1847 | For example, suppose that the signal handler uses @code{gethostbyname}. | |
1848 | This function returns its value in a static object, reusing the same | |
1849 | object each time. If the signal happens to arrive during a call to | |
1850 | @code{gethostbyname}, or even after one (while the program is still | |
1851 | using the value), it will clobber the value that the program asked for. | |
1852 | ||
1853 | However, if the program does not use @code{gethostbyname} or any other | |
1854 | function that returns information in the same object, or if it always | |
1855 | blocks signals around each use, then you are safe. | |
1856 | ||
1857 | There are a large number of library functions that return values in a | |
1858 | fixed object, always reusing the same object in this fashion, and all of | |
a496e4ce | 1859 | them cause the same problem. Function descriptions in this manual |
04b9968b | 1860 | always mention this behavior. |
28f540f4 RM |
1861 | |
1862 | @item | |
1863 | If a function uses and modifies an object that you supply, then it is | |
1864 | potentially non-reentrant; two calls can interfere if they use the same | |
1865 | object. | |
1866 | ||
1867 | This case arises when you do I/O using streams. Suppose that the | |
1868 | signal handler prints a message with @code{fprintf}. Suppose that the | |
1869 | program was in the middle of an @code{fprintf} call using the same | |
1870 | stream when the signal was delivered. Both the signal handler's message | |
1871 | and the program's data could be corrupted, because both calls operate on | |
1872 | the same data structure---the stream itself. | |
1873 | ||
1874 | However, if you know that the stream that the handler uses cannot | |
1875 | possibly be used by the program at a time when signals can arrive, then | |
1876 | you are safe. It is no problem if the program uses some other stream. | |
1877 | ||
1878 | @item | |
1879 | On most systems, @code{malloc} and @code{free} are not reentrant, | |
1880 | because they use a static data structure which records what memory | |
1881 | blocks are free. As a result, no library functions that allocate or | |
1882 | free memory are reentrant. This includes functions that allocate space | |
1883 | to store a result. | |
1884 | ||
1885 | The best way to avoid the need to allocate memory in a handler is to | |
1886 | allocate in advance space for signal handlers to use. | |
1887 | ||
1888 | The best way to avoid freeing memory in a handler is to flag or record | |
1889 | the objects to be freed, and have the program check from time to time | |
1890 | whether anything is waiting to be freed. But this must be done with | |
1891 | care, because placing an object on a chain is not atomic, and if it is | |
1892 | interrupted by another signal handler that does the same thing, you | |
1893 | could ``lose'' one of the objects. | |
1894 | ||
1895 | @ignore | |
1896 | !!! not true | |
a7a93d50 | 1897 | In @theglibc{}, @code{malloc} and @code{free} are safe to use in |
28f540f4 RM |
1898 | signal handlers because they block signals. As a result, the library |
1899 | functions that allocate space for a result are also safe in signal | |
1900 | handlers. The obstack allocation functions are safe as long as you | |
1901 | don't use the same obstack both inside and outside of a signal handler. | |
1902 | @end ignore | |
1903 | ||
a9ddb793 UD |
1904 | @ignore |
1905 | @comment Once we have r_alloc again add this paragraph. | |
28f540f4 RM |
1906 | The relocating allocation functions (@pxref{Relocating Allocator}) |
1907 | are certainly not safe to use in a signal handler. | |
a9ddb793 | 1908 | @end ignore |
28f540f4 RM |
1909 | |
1910 | @item | |
1911 | Any function that modifies @code{errno} is non-reentrant, but you can | |
1912 | correct for this: in the handler, save the original value of | |
1913 | @code{errno} and restore it before returning normally. This prevents | |
1914 | errors that occur within the signal handler from being confused with | |
1915 | errors from system calls at the point the program is interrupted to run | |
1916 | the handler. | |
1917 | ||
1918 | This technique is generally applicable; if you want to call in a handler | |
1919 | a function that modifies a particular object in memory, you can make | |
1920 | this safe by saving and restoring that object. | |
1921 | ||
1922 | @item | |
1923 | Merely reading from a memory object is safe provided that you can deal | |
1924 | with any of the values that might appear in the object at a time when | |
1925 | the signal can be delivered. Keep in mind that assignment to some data | |
1926 | types requires more than one instruction, which means that the handler | |
1927 | could run ``in the middle of'' an assignment to the variable if its type | |
1928 | is not atomic. @xref{Atomic Data Access}. | |
1929 | ||
1930 | @item | |
1931 | Merely writing into a memory object is safe as long as a sudden change | |
1932 | in the value, at any time when the handler might run, will not disturb | |
1933 | anything. | |
1934 | @end itemize | |
1935 | ||
1936 | @node Atomic Data Access | |
1937 | @subsection Atomic Data Access and Signal Handling | |
1938 | ||
1939 | Whether the data in your application concerns atoms, or mere text, you | |
1940 | have to be careful about the fact that access to a single datum is not | |
1941 | necessarily @dfn{atomic}. This means that it can take more than one | |
1942 | instruction to read or write a single object. In such cases, a signal | |
04b9968b | 1943 | handler might be invoked in the middle of reading or writing the object. |
28f540f4 RM |
1944 | |
1945 | There are three ways you can cope with this problem. You can use data | |
1946 | types that are always accessed atomically; you can carefully arrange | |
1947 | that nothing untoward happens if an access is interrupted, or you can | |
1948 | block all signals around any access that had better not be interrupted | |
1949 | (@pxref{Blocking Signals}). | |
1950 | ||
1951 | @menu | |
1952 | * Non-atomic Example:: A program illustrating interrupted access. | |
1953 | * Types: Atomic Types. Data types that guarantee no interruption. | |
1954 | * Usage: Atomic Usage. Proving that interruption is harmless. | |
1955 | @end menu | |
1956 | ||
1957 | @node Non-atomic Example | |
1958 | @subsubsection Problems with Non-Atomic Access | |
1959 | ||
1960 | Here is an example which shows what can happen if a signal handler runs | |
1961 | in the middle of modifying a variable. (Interrupting the reading of a | |
1962 | variable can also lead to paradoxical results, but here we only show | |
1963 | writing.) | |
1964 | ||
1965 | @smallexample | |
1966 | #include <signal.h> | |
1967 | #include <stdio.h> | |
1968 | ||
403445d7 | 1969 | volatile struct two_words @{ int a, b; @} memory; |
28f540f4 RM |
1970 | |
1971 | void | |
1972 | handler(int signum) | |
1973 | @{ | |
1974 | printf ("%d,%d\n", memory.a, memory.b); | |
1975 | alarm (1); | |
1976 | @} | |
1977 | ||
1978 | @group | |
1979 | int | |
1980 | main (void) | |
1981 | @{ | |
1982 | static struct two_words zeros = @{ 0, 0 @}, ones = @{ 1, 1 @}; | |
1983 | signal (SIGALRM, handler); | |
1984 | memory = zeros; | |
1985 | alarm (1); | |
1986 | while (1) | |
1987 | @{ | |
1988 | memory = zeros; | |
1989 | memory = ones; | |
1990 | @} | |
1991 | @} | |
1992 | @end group | |
1993 | @end smallexample | |
1994 | ||
1995 | This program fills @code{memory} with zeros, ones, zeros, ones, | |
1996 | alternating forever; meanwhile, once per second, the alarm signal handler | |
1997 | prints the current contents. (Calling @code{printf} in the handler is | |
1998 | safe in this program because it is certainly not being called outside | |
1999 | the handler when the signal happens.) | |
2000 | ||
2001 | Clearly, this program can print a pair of zeros or a pair of ones. But | |
2002 | that's not all it can do! On most machines, it takes several | |
2003 | instructions to store a new value in @code{memory}, and the value is | |
2004 | stored one word at a time. If the signal is delivered in between these | |
2005 | instructions, the handler might find that @code{memory.a} is zero and | |
2006 | @code{memory.b} is one (or vice versa). | |
2007 | ||
2008 | On some machines it may be possible to store a new value in | |
2009 | @code{memory} with just one instruction that cannot be interrupted. On | |
2010 | these machines, the handler will always print two zeros or two ones. | |
2011 | ||
2012 | @node Atomic Types | |
2013 | @subsubsection Atomic Types | |
2014 | ||
2015 | To avoid uncertainty about interrupting access to a variable, you can | |
2016 | use a particular data type for which access is always atomic: | |
2017 | @code{sig_atomic_t}. Reading and writing this data type is guaranteed | |
2018 | to happen in a single instruction, so there's no way for a handler to | |
2019 | run ``in the middle'' of an access. | |
2020 | ||
2021 | The type @code{sig_atomic_t} is always an integer data type, but which | |
2022 | one it is, and how many bits it contains, may vary from machine to | |
2023 | machine. | |
2024 | ||
2025 | @comment signal.h | |
f65fd747 | 2026 | @comment ISO |
28f540f4 RM |
2027 | @deftp {Data Type} sig_atomic_t |
2028 | This is an integer data type. Objects of this type are always accessed | |
2029 | atomically. | |
2030 | @end deftp | |
2031 | ||
bb5037cd UD |
2032 | In practice, you can assume that @code{int} is atomic. |
2033 | You can also assume that pointer | |
a496e4ce | 2034 | types are atomic; that is very convenient. Both of these assumptions |
1f77f049 | 2035 | are true on all of the machines that @theglibc{} supports and on |
04b9968b | 2036 | all POSIX systems we know of. |
28f540f4 RM |
2037 | @c ??? This might fail on a 386 that uses 64-bit pointers. |
2038 | ||
2039 | @node Atomic Usage | |
2040 | @subsubsection Atomic Usage Patterns | |
2041 | ||
2042 | Certain patterns of access avoid any problem even if an access is | |
2043 | interrupted. For example, a flag which is set by the handler, and | |
2044 | tested and cleared by the main program from time to time, is always safe | |
2045 | even if access actually requires two instructions. To show that this is | |
2046 | so, we must consider each access that could be interrupted, and show | |
2047 | that there is no problem if it is interrupted. | |
2048 | ||
2049 | An interrupt in the middle of testing the flag is safe because either it's | |
2050 | recognized to be nonzero, in which case the precise value doesn't | |
2051 | matter, or it will be seen to be nonzero the next time it's tested. | |
2052 | ||
2053 | An interrupt in the middle of clearing the flag is no problem because | |
2054 | either the value ends up zero, which is what happens if a signal comes | |
2055 | in just before the flag is cleared, or the value ends up nonzero, and | |
2056 | subsequent events occur as if the signal had come in just after the flag | |
2057 | was cleared. As long as the code handles both of these cases properly, | |
2058 | it can also handle a signal in the middle of clearing the flag. (This | |
2059 | is an example of the sort of reasoning you need to do to figure out | |
2060 | whether non-atomic usage is safe.) | |
2061 | ||
2062 | Sometimes you can insure uninterrupted access to one object by | |
2063 | protecting its use with another object, perhaps one whose type | |
2064 | guarantees atomicity. @xref{Merged Signals}, for an example. | |
2065 | ||
2066 | @node Interrupted Primitives | |
2067 | @section Primitives Interrupted by Signals | |
2068 | ||
2069 | A signal can arrive and be handled while an I/O primitive such as | |
2070 | @code{open} or @code{read} is waiting for an I/O device. If the signal | |
2071 | handler returns, the system faces the question: what should happen next? | |
2072 | ||
2073 | POSIX specifies one approach: make the primitive fail right away. The | |
2074 | error code for this kind of failure is @code{EINTR}. This is flexible, | |
2075 | but usually inconvenient. Typically, POSIX applications that use signal | |
2076 | handlers must check for @code{EINTR} after each library function that | |
2077 | can return it, in order to try the call again. Often programmers forget | |
2078 | to check, which is a common source of error. | |
2079 | ||
1f77f049 | 2080 | @Theglibc{} provides a convenient way to retry a call after a |
28f540f4 RM |
2081 | temporary failure, with the macro @code{TEMP_FAILURE_RETRY}: |
2082 | ||
2083 | @comment unistd.h | |
2084 | @comment GNU | |
2085 | @defmac TEMP_FAILURE_RETRY (@var{expression}) | |
36634622 RM |
2086 | This macro evaluates @var{expression} once, and examines its value as |
2087 | type @code{long int}. If the value equals @code{-1}, that indicates a | |
2088 | failure and @code{errno} should be set to show what kind of failure. | |
2089 | If it fails and reports error code @code{EINTR}, | |
2090 | @code{TEMP_FAILURE_RETRY} evaluates it again, and over and over until | |
2091 | the result is not a temporary failure. | |
28f540f4 RM |
2092 | |
2093 | The value returned by @code{TEMP_FAILURE_RETRY} is whatever value | |
2094 | @var{expression} produced. | |
2095 | @end defmac | |
2096 | ||
2097 | BSD avoids @code{EINTR} entirely and provides a more convenient | |
2098 | approach: to restart the interrupted primitive, instead of making it | |
2099 | fail. If you choose this approach, you need not be concerned with | |
2100 | @code{EINTR}. | |
2101 | ||
1f77f049 | 2102 | You can choose either approach with @theglibc{}. If you use |
28f540f4 RM |
2103 | @code{sigaction} to establish a signal handler, you can specify how that |
2104 | handler should behave. If you specify the @code{SA_RESTART} flag, | |
2105 | return from that handler will resume a primitive; otherwise, return from | |
2106 | that handler will cause @code{EINTR}. @xref{Flags for Sigaction}. | |
2107 | ||
2108 | Another way to specify the choice is with the @code{siginterrupt} | |
2109 | function. @xref{BSD Handler}. | |
2110 | ||
2111 | @c !!! not true now about _BSD_SOURCE | |
2112 | When you don't specify with @code{sigaction} or @code{siginterrupt} what | |
2113 | a particular handler should do, it uses a default choice. The default | |
1f77f049 | 2114 | choice in @theglibc{} depends on the feature test macros you have |
28f540f4 RM |
2115 | defined. If you define @code{_BSD_SOURCE} or @code{_GNU_SOURCE} before |
2116 | calling @code{signal}, the default is to resume primitives; otherwise, | |
2117 | the default is to make them fail with @code{EINTR}. (The library | |
2118 | contains alternate versions of the @code{signal} function, and the | |
2119 | feature test macros determine which one you really call.) @xref{Feature | |
2120 | Test Macros}. | |
2121 | @cindex EINTR, and restarting interrupted primitives | |
2122 | @cindex restarting interrupted primitives | |
2123 | @cindex interrupting primitives | |
2124 | @cindex primitives, interrupting | |
2125 | @c !!! want to have @cindex system calls @i{see} primitives [no page #] | |
2126 | ||
2127 | The description of each primitive affected by this issue | |
2128 | lists @code{EINTR} among the error codes it can return. | |
2129 | ||
2130 | There is one situation where resumption never happens no matter which | |
2131 | choice you make: when a data-transfer function such as @code{read} or | |
2132 | @code{write} is interrupted by a signal after transferring part of the | |
2133 | data. In this case, the function returns the number of bytes already | |
2134 | transferred, indicating partial success. | |
2135 | ||
2136 | This might at first appear to cause unreliable behavior on | |
2137 | record-oriented devices (including datagram sockets; @pxref{Datagrams}), | |
2138 | where splitting one @code{read} or @code{write} into two would read or | |
2139 | write two records. Actually, there is no problem, because interruption | |
2140 | after a partial transfer cannot happen on such devices; they always | |
2141 | transfer an entire record in one burst, with no waiting once data | |
2142 | transfer has started. | |
2143 | ||
2144 | @node Generating Signals | |
2145 | @section Generating Signals | |
2146 | @cindex sending signals | |
2147 | @cindex raising signals | |
2148 | @cindex signals, generating | |
2149 | ||
2150 | Besides signals that are generated as a result of a hardware trap or | |
2151 | interrupt, your program can explicitly send signals to itself or to | |
2152 | another process. | |
2153 | ||
2154 | @menu | |
2155 | * Signaling Yourself:: A process can send a signal to itself. | |
2156 | * Signaling Another Process:: Send a signal to another process. | |
2157 | * Permission for kill:: Permission for using @code{kill}. | |
2158 | * Kill Example:: Using @code{kill} for Communication. | |
2159 | @end menu | |
2160 | ||
2161 | @node Signaling Yourself | |
2162 | @subsection Signaling Yourself | |
2163 | ||
2164 | A process can send itself a signal with the @code{raise} function. This | |
2165 | function is declared in @file{signal.h}. | |
2166 | @pindex signal.h | |
2167 | ||
2168 | @comment signal.h | |
f65fd747 | 2169 | @comment ISO |
28f540f4 RM |
2170 | @deftypefun int raise (int @var{signum}) |
2171 | The @code{raise} function sends the signal @var{signum} to the calling | |
2172 | process. It returns zero if successful and a nonzero value if it fails. | |
2173 | About the only reason for failure would be if the value of @var{signum} | |
2174 | is invalid. | |
2175 | @end deftypefun | |
2176 | ||
2177 | @comment signal.h | |
2178 | @comment SVID | |
2179 | @deftypefun int gsignal (int @var{signum}) | |
2180 | The @code{gsignal} function does the same thing as @code{raise}; it is | |
2181 | provided only for compatibility with SVID. | |
2182 | @end deftypefun | |
2183 | ||
2184 | One convenient use for @code{raise} is to reproduce the default behavior | |
2185 | of a signal that you have trapped. For instance, suppose a user of your | |
2186 | program types the SUSP character (usually @kbd{C-z}; @pxref{Special | |
fed8f7f7 | 2187 | Characters}) to send it an interactive stop signal |
28f540f4 RM |
2188 | (@code{SIGTSTP}), and you want to clean up some internal data buffers |
2189 | before stopping. You might set this up like this: | |
2190 | ||
2191 | @comment RMS suggested getting rid of the handler for SIGCONT in this function. | |
2192 | @comment But that would require that the handler for SIGTSTP unblock the | |
2193 | @comment signal before doing the call to raise. We haven't covered that | |
2194 | @comment topic yet, and I don't want to distract from the main point of | |
2195 | @comment the example with a digression to explain what is going on. As | |
2196 | @comment the example is written, the signal that is raise'd will be delivered | |
2197 | @comment as soon as the SIGTSTP handler returns, which is fine. | |
2198 | ||
2199 | @smallexample | |
2200 | #include <signal.h> | |
2201 | ||
2202 | /* @r{When a stop signal arrives, set the action back to the default | |
2203 | and then resend the signal after doing cleanup actions.} */ | |
2204 | ||
2205 | void | |
2206 | tstp_handler (int sig) | |
2207 | @{ | |
2208 | signal (SIGTSTP, SIG_DFL); | |
2209 | /* @r{Do cleanup actions here.} */ | |
2210 | @dots{} | |
2211 | raise (SIGTSTP); | |
2212 | @} | |
2213 | ||
2214 | /* @r{When the process is continued again, restore the signal handler.} */ | |
2215 | ||
2216 | void | |
2217 | cont_handler (int sig) | |
2218 | @{ | |
2219 | signal (SIGCONT, cont_handler); | |
2220 | signal (SIGTSTP, tstp_handler); | |
2221 | @} | |
2222 | ||
2223 | @group | |
2224 | /* @r{Enable both handlers during program initialization.} */ | |
2225 | ||
2226 | int | |
2227 | main (void) | |
2228 | @{ | |
2229 | signal (SIGCONT, cont_handler); | |
2230 | signal (SIGTSTP, tstp_handler); | |
2231 | @dots{} | |
2232 | @} | |
2233 | @end group | |
2234 | @end smallexample | |
2235 | ||
f65fd747 | 2236 | @strong{Portability note:} @code{raise} was invented by the @w{ISO C} |
28f540f4 RM |
2237 | committee. Older systems may not support it, so using @code{kill} may |
2238 | be more portable. @xref{Signaling Another Process}. | |
2239 | ||
2240 | @node Signaling Another Process | |
2241 | @subsection Signaling Another Process | |
2242 | ||
2243 | @cindex killing a process | |
2244 | The @code{kill} function can be used to send a signal to another process. | |
2245 | In spite of its name, it can be used for a lot of things other than | |
2246 | causing a process to terminate. Some examples of situations where you | |
2247 | might want to send signals between processes are: | |
2248 | ||
2249 | @itemize @bullet | |
2250 | @item | |
2251 | A parent process starts a child to perform a task---perhaps having the | |
2252 | child running an infinite loop---and then terminates the child when the | |
2253 | task is no longer needed. | |
2254 | ||
2255 | @item | |
2256 | A process executes as part of a group, and needs to terminate or notify | |
2257 | the other processes in the group when an error or other event occurs. | |
2258 | ||
2259 | @item | |
2260 | Two processes need to synchronize while working together. | |
2261 | @end itemize | |
2262 | ||
2263 | This section assumes that you know a little bit about how processes | |
2264 | work. For more information on this subject, see @ref{Processes}. | |
2265 | ||
2266 | The @code{kill} function is declared in @file{signal.h}. | |
2267 | @pindex signal.h | |
2268 | ||
2269 | @comment signal.h | |
2270 | @comment POSIX.1 | |
2271 | @deftypefun int kill (pid_t @var{pid}, int @var{signum}) | |
2272 | The @code{kill} function sends the signal @var{signum} to the process | |
2273 | or process group specified by @var{pid}. Besides the signals listed in | |
2274 | @ref{Standard Signals}, @var{signum} can also have a value of zero to | |
2275 | check the validity of the @var{pid}. | |
2276 | ||
2277 | The @var{pid} specifies the process or process group to receive the | |
2278 | signal: | |
2279 | ||
2280 | @table @code | |
2281 | @item @var{pid} > 0 | |
2282 | The process whose identifier is @var{pid}. | |
2283 | ||
2284 | @item @var{pid} == 0 | |
2285 | All processes in the same process group as the sender. | |
2286 | ||
2287 | @item @var{pid} < -1 | |
2288 | The process group whose identifier is @minus{}@var{pid}. | |
2289 | ||
2290 | @item @var{pid} == -1 | |
2291 | If the process is privileged, send the signal to all processes except | |
2292 | for some special system processes. Otherwise, send the signal to all | |
2293 | processes with the same effective user ID. | |
2294 | @end table | |
2295 | ||
838e5ffe UD |
2296 | A process can send a signal to itself with a call like @w{@code{kill |
2297 | (getpid(), @var{signum})}}. If @code{kill} is used by a process to send | |
2298 | a signal to itself, and the signal is not blocked, then @code{kill} | |
2299 | delivers at least one signal (which might be some other pending | |
2300 | unblocked signal instead of the signal @var{signum}) to that process | |
2301 | before it returns. | |
28f540f4 RM |
2302 | |
2303 | The return value from @code{kill} is zero if the signal can be sent | |
2304 | successfully. Otherwise, no signal is sent, and a value of @code{-1} is | |
2305 | returned. If @var{pid} specifies sending a signal to several processes, | |
2306 | @code{kill} succeeds if it can send the signal to at least one of them. | |
2307 | There's no way you can tell which of the processes got the signal | |
2308 | or whether all of them did. | |
2309 | ||
2310 | The following @code{errno} error conditions are defined for this function: | |
2311 | ||
2312 | @table @code | |
2313 | @item EINVAL | |
2314 | The @var{signum} argument is an invalid or unsupported number. | |
2315 | ||
2316 | @item EPERM | |
2317 | You do not have the privilege to send a signal to the process or any of | |
2318 | the processes in the process group named by @var{pid}. | |
2319 | ||
4cc6384d | 2320 | @item ESRCH |
28f540f4 RM |
2321 | The @var{pid} argument does not refer to an existing process or group. |
2322 | @end table | |
2323 | @end deftypefun | |
2324 | ||
2325 | @comment signal.h | |
2326 | @comment BSD | |
2327 | @deftypefun int killpg (int @var{pgid}, int @var{signum}) | |
2328 | This is similar to @code{kill}, but sends signal @var{signum} to the | |
2329 | process group @var{pgid}. This function is provided for compatibility | |
2330 | with BSD; using @code{kill} to do this is more portable. | |
2331 | @end deftypefun | |
2332 | ||
2333 | As a simple example of @code{kill}, the call @w{@code{kill (getpid (), | |
2334 | @var{sig})}} has the same effect as @w{@code{raise (@var{sig})}}. | |
2335 | ||
2336 | @node Permission for kill | |
2337 | @subsection Permission for using @code{kill} | |
2338 | ||
2339 | There are restrictions that prevent you from using @code{kill} to send | |
2340 | signals to any random process. These are intended to prevent antisocial | |
2341 | behavior such as arbitrarily killing off processes belonging to another | |
2342 | user. In typical use, @code{kill} is used to pass signals between | |
2343 | parent, child, and sibling processes, and in these situations you | |
6d52618b | 2344 | normally do have permission to send signals. The only common exception |
28f540f4 RM |
2345 | is when you run a setuid program in a child process; if the program |
2346 | changes its real UID as well as its effective UID, you may not have | |
2347 | permission to send a signal. The @code{su} program does this. | |
2348 | ||
2349 | Whether a process has permission to send a signal to another process | |
2350 | is determined by the user IDs of the two processes. This concept is | |
2351 | discussed in detail in @ref{Process Persona}. | |
2352 | ||
2353 | Generally, for a process to be able to send a signal to another process, | |
2354 | either the sending process must belong to a privileged user (like | |
2355 | @samp{root}), or the real or effective user ID of the sending process | |
2356 | must match the real or effective user ID of the receiving process. If | |
2357 | the receiving process has changed its effective user ID from the | |
2358 | set-user-ID mode bit on its process image file, then the owner of the | |
2359 | process image file is used in place of its current effective user ID. | |
2360 | In some implementations, a parent process might be able to send signals | |
2361 | to a child process even if the user ID's don't match, and other | |
2362 | implementations might enforce other restrictions. | |
2363 | ||
2364 | The @code{SIGCONT} signal is a special case. It can be sent if the | |
2365 | sender is part of the same session as the receiver, regardless of | |
2366 | user IDs. | |
2367 | ||
2368 | @node Kill Example | |
2369 | @subsection Using @code{kill} for Communication | |
2370 | @cindex interprocess communication, with signals | |
2371 | Here is a longer example showing how signals can be used for | |
2372 | interprocess communication. This is what the @code{SIGUSR1} and | |
2373 | @code{SIGUSR2} signals are provided for. Since these signals are fatal | |
2374 | by default, the process that is supposed to receive them must trap them | |
2375 | through @code{signal} or @code{sigaction}. | |
2376 | ||
2377 | In this example, a parent process forks a child process and then waits | |
2378 | for the child to complete its initialization. The child process tells | |
2379 | the parent when it is ready by sending it a @code{SIGUSR1} signal, using | |
2380 | the @code{kill} function. | |
2381 | ||
2382 | @smallexample | |
2383 | @include sigusr.c.texi | |
2384 | @end smallexample | |
2385 | ||
2386 | This example uses a busy wait, which is bad, because it wastes CPU | |
2387 | cycles that other programs could otherwise use. It is better to ask the | |
2388 | system to wait until the signal arrives. See the example in | |
2389 | @ref{Waiting for a Signal}. | |
2390 | ||
2391 | @node Blocking Signals | |
2392 | @section Blocking Signals | |
2393 | @cindex blocking signals | |
2394 | ||
2395 | Blocking a signal means telling the operating system to hold it and | |
2396 | deliver it later. Generally, a program does not block signals | |
2397 | indefinitely---it might as well ignore them by setting their actions to | |
2398 | @code{SIG_IGN}. But it is useful to block signals briefly, to prevent | |
2399 | them from interrupting sensitive operations. For instance: | |
2400 | ||
2401 | @itemize @bullet | |
2402 | @item | |
2403 | You can use the @code{sigprocmask} function to block signals while you | |
f65fd747 | 2404 | modify global variables that are also modified by the handlers for these |
28f540f4 RM |
2405 | signals. |
2406 | ||
2407 | @item | |
2408 | You can set @code{sa_mask} in your @code{sigaction} call to block | |
2409 | certain signals while a particular signal handler runs. This way, the | |
2410 | signal handler can run without being interrupted itself by signals. | |
2411 | @end itemize | |
2412 | ||
2413 | @menu | |
2414 | * Why Block:: The purpose of blocking signals. | |
2415 | * Signal Sets:: How to specify which signals to | |
f65fd747 | 2416 | block. |
28f540f4 RM |
2417 | * Process Signal Mask:: Blocking delivery of signals to your |
2418 | process during normal execution. | |
2419 | * Testing for Delivery:: Blocking to Test for Delivery of | |
f65fd747 | 2420 | a Signal. |
28f540f4 RM |
2421 | * Blocking for Handler:: Blocking additional signals while a |
2422 | handler is being run. | |
2423 | * Checking for Pending Signals:: Checking for Pending Signals | |
2424 | * Remembering a Signal:: How you can get almost the same | |
2425 | effect as blocking a signal, by | |
2426 | handling it and setting a flag | |
f65fd747 | 2427 | to be tested later. |
28f540f4 RM |
2428 | @end menu |
2429 | ||
2430 | @node Why Block | |
2431 | @subsection Why Blocking Signals is Useful | |
2432 | ||
2433 | Temporary blocking of signals with @code{sigprocmask} gives you a way to | |
2434 | prevent interrupts during critical parts of your code. If signals | |
2435 | arrive in that part of the program, they are delivered later, after you | |
2436 | unblock them. | |
2437 | ||
2438 | One example where this is useful is for sharing data between a signal | |
2439 | handler and the rest of the program. If the type of the data is not | |
2440 | @code{sig_atomic_t} (@pxref{Atomic Data Access}), then the signal | |
2441 | handler could run when the rest of the program has only half finished | |
2442 | reading or writing the data. This would lead to confusing consequences. | |
2443 | ||
2444 | To make the program reliable, you can prevent the signal handler from | |
2445 | running while the rest of the program is examining or modifying that | |
2446 | data---by blocking the appropriate signal around the parts of the | |
2447 | program that touch the data. | |
2448 | ||
2449 | Blocking signals is also necessary when you want to perform a certain | |
2450 | action only if a signal has not arrived. Suppose that the handler for | |
2451 | the signal sets a flag of type @code{sig_atomic_t}; you would like to | |
2452 | test the flag and perform the action if the flag is not set. This is | |
2453 | unreliable. Suppose the signal is delivered immediately after you test | |
2454 | the flag, but before the consequent action: then the program will | |
2455 | perform the action even though the signal has arrived. | |
2456 | ||
2457 | The only way to test reliably for whether a signal has yet arrived is to | |
2458 | test while the signal is blocked. | |
2459 | ||
2460 | @node Signal Sets | |
2461 | @subsection Signal Sets | |
2462 | ||
2463 | All of the signal blocking functions use a data structure called a | |
2464 | @dfn{signal set} to specify what signals are affected. Thus, every | |
2465 | activity involves two stages: creating the signal set, and then passing | |
2466 | it as an argument to a library function. | |
2467 | @cindex signal set | |
2468 | ||
2469 | These facilities are declared in the header file @file{signal.h}. | |
2470 | @pindex signal.h | |
2471 | ||
2472 | @comment signal.h | |
2473 | @comment POSIX.1 | |
2474 | @deftp {Data Type} sigset_t | |
2475 | The @code{sigset_t} data type is used to represent a signal set. | |
2476 | Internally, it may be implemented as either an integer or structure | |
2477 | type. | |
2478 | ||
2479 | For portability, use only the functions described in this section to | |
2480 | initialize, change, and retrieve information from @code{sigset_t} | |
2481 | objects---don't try to manipulate them directly. | |
2482 | @end deftp | |
2483 | ||
2484 | There are two ways to initialize a signal set. You can initially | |
2485 | specify it to be empty with @code{sigemptyset} and then add specified | |
2486 | signals individually. Or you can specify it to be full with | |
2487 | @code{sigfillset} and then delete specified signals individually. | |
2488 | ||
2489 | You must always initialize the signal set with one of these two | |
2490 | functions before using it in any other way. Don't try to set all the | |
2491 | signals explicitly because the @code{sigset_t} object might include some | |
2492 | other information (like a version field) that needs to be initialized as | |
2493 | well. (In addition, it's not wise to put into your program an | |
2494 | assumption that the system has no signals aside from the ones you know | |
2495 | about.) | |
2496 | ||
2497 | @comment signal.h | |
2498 | @comment POSIX.1 | |
2499 | @deftypefun int sigemptyset (sigset_t *@var{set}) | |
2500 | This function initializes the signal set @var{set} to exclude all of the | |
2501 | defined signals. It always returns @code{0}. | |
2502 | @end deftypefun | |
2503 | ||
2504 | @comment signal.h | |
2505 | @comment POSIX.1 | |
2506 | @deftypefun int sigfillset (sigset_t *@var{set}) | |
2507 | This function initializes the signal set @var{set} to include | |
2508 | all of the defined signals. Again, the return value is @code{0}. | |
2509 | @end deftypefun | |
2510 | ||
2511 | @comment signal.h | |
2512 | @comment POSIX.1 | |
2513 | @deftypefun int sigaddset (sigset_t *@var{set}, int @var{signum}) | |
2514 | This function adds the signal @var{signum} to the signal set @var{set}. | |
2515 | All @code{sigaddset} does is modify @var{set}; it does not block or | |
2516 | unblock any signals. | |
2517 | ||
2518 | The return value is @code{0} on success and @code{-1} on failure. | |
2519 | The following @code{errno} error condition is defined for this function: | |
2520 | ||
2521 | @table @code | |
2522 | @item EINVAL | |
2523 | The @var{signum} argument doesn't specify a valid signal. | |
2524 | @end table | |
2525 | @end deftypefun | |
2526 | ||
2527 | @comment signal.h | |
2528 | @comment POSIX.1 | |
2529 | @deftypefun int sigdelset (sigset_t *@var{set}, int @var{signum}) | |
2530 | This function removes the signal @var{signum} from the signal set | |
2531 | @var{set}. All @code{sigdelset} does is modify @var{set}; it does not | |
2532 | block or unblock any signals. The return value and error conditions are | |
2533 | the same as for @code{sigaddset}. | |
2534 | @end deftypefun | |
2535 | ||
2536 | Finally, there is a function to test what signals are in a signal set: | |
2537 | ||
2538 | @comment signal.h | |
2539 | @comment POSIX.1 | |
2540 | @deftypefun int sigismember (const sigset_t *@var{set}, int @var{signum}) | |
2541 | The @code{sigismember} function tests whether the signal @var{signum} is | |
2542 | a member of the signal set @var{set}. It returns @code{1} if the signal | |
2543 | is in the set, @code{0} if not, and @code{-1} if there is an error. | |
2544 | ||
2545 | The following @code{errno} error condition is defined for this function: | |
2546 | ||
2547 | @table @code | |
2548 | @item EINVAL | |
2549 | The @var{signum} argument doesn't specify a valid signal. | |
2550 | @end table | |
2551 | @end deftypefun | |
2552 | ||
2553 | @node Process Signal Mask | |
2554 | @subsection Process Signal Mask | |
2555 | @cindex signal mask | |
2556 | @cindex process signal mask | |
2557 | ||
2558 | The collection of signals that are currently blocked is called the | |
2559 | @dfn{signal mask}. Each process has its own signal mask. When you | |
2560 | create a new process (@pxref{Creating a Process}), it inherits its | |
2561 | parent's mask. You can block or unblock signals with total flexibility | |
2562 | by modifying the signal mask. | |
2563 | ||
2564 | The prototype for the @code{sigprocmask} function is in @file{signal.h}. | |
2565 | @pindex signal.h | |
2566 | ||
afdef815 UD |
2567 | Note that you must not use @code{sigprocmask} in multi-threaded processes, |
2568 | because each thread has its own signal mask and there is no single process | |
2569 | signal mask. According to POSIX, the behavior of @code{sigprocmask} in a | |
11bf311e | 2570 | multi-threaded process is ``unspecified''. |
f0baa823 RM |
2571 | Instead, use @code{pthread_sigmask}. |
2572 | @ifset linuxthreads | |
2573 | @xref{Threads and Signal Handling}. | |
2574 | @end ifset | |
afdef815 | 2575 | |
28f540f4 RM |
2576 | @comment signal.h |
2577 | @comment POSIX.1 | |
eacde9d0 | 2578 | @deftypefun int sigprocmask (int @var{how}, const sigset_t *restrict @var{set}, sigset_t *restrict @var{oldset}) |
28f540f4 RM |
2579 | The @code{sigprocmask} function is used to examine or change the calling |
2580 | process's signal mask. The @var{how} argument determines how the signal | |
2581 | mask is changed, and must be one of the following values: | |
2582 | ||
2583 | @table @code | |
2584 | @comment signal.h | |
2585 | @comment POSIX.1 | |
2586 | @vindex SIG_BLOCK | |
2587 | @item SIG_BLOCK | |
2588 | Block the signals in @code{set}---add them to the existing mask. In | |
2589 | other words, the new mask is the union of the existing mask and | |
2590 | @var{set}. | |
2591 | ||
2592 | @comment signal.h | |
2593 | @comment POSIX.1 | |
2594 | @vindex SIG_UNBLOCK | |
2595 | @item SIG_UNBLOCK | |
2596 | Unblock the signals in @var{set}---remove them from the existing mask. | |
2597 | ||
2598 | @comment signal.h | |
2599 | @comment POSIX.1 | |
2600 | @vindex SIG_SETMASK | |
2601 | @item SIG_SETMASK | |
2602 | Use @var{set} for the mask; ignore the previous value of the mask. | |
2603 | @end table | |
2604 | ||
2605 | The last argument, @var{oldset}, is used to return information about the | |
2606 | old process signal mask. If you just want to change the mask without | |
2607 | looking at it, pass a null pointer as the @var{oldset} argument. | |
2608 | Similarly, if you want to know what's in the mask without changing it, | |
2609 | pass a null pointer for @var{set} (in this case the @var{how} argument | |
2610 | is not significant). The @var{oldset} argument is often used to | |
2611 | remember the previous signal mask in order to restore it later. (Since | |
2612 | the signal mask is inherited over @code{fork} and @code{exec} calls, you | |
2613 | can't predict what its contents are when your program starts running.) | |
2614 | ||
2615 | If invoking @code{sigprocmask} causes any pending signals to be | |
2616 | unblocked, at least one of those signals is delivered to the process | |
2617 | before @code{sigprocmask} returns. The order in which pending signals | |
2618 | are delivered is not specified, but you can control the order explicitly | |
2619 | by making multiple @code{sigprocmask} calls to unblock various signals | |
2620 | one at a time. | |
2621 | ||
2622 | The @code{sigprocmask} function returns @code{0} if successful, and @code{-1} | |
2623 | to indicate an error. The following @code{errno} error conditions are | |
2624 | defined for this function: | |
2625 | ||
2626 | @table @code | |
2627 | @item EINVAL | |
2628 | The @var{how} argument is invalid. | |
2629 | @end table | |
2630 | ||
2631 | You can't block the @code{SIGKILL} and @code{SIGSTOP} signals, but | |
2632 | if the signal set includes these, @code{sigprocmask} just ignores | |
2633 | them instead of returning an error status. | |
2634 | ||
2635 | Remember, too, that blocking program error signals such as @code{SIGFPE} | |
2636 | leads to undesirable results for signals generated by an actual program | |
2637 | error (as opposed to signals sent with @code{raise} or @code{kill}). | |
2638 | This is because your program may be too broken to be able to continue | |
2639 | executing to a point where the signal is unblocked again. | |
2640 | @xref{Program Error Signals}. | |
2641 | @end deftypefun | |
2642 | ||
2643 | @node Testing for Delivery | |
2644 | @subsection Blocking to Test for Delivery of a Signal | |
2645 | ||
2646 | Now for a simple example. Suppose you establish a handler for | |
2647 | @code{SIGALRM} signals that sets a flag whenever a signal arrives, and | |
2648 | your main program checks this flag from time to time and then resets it. | |
2649 | You can prevent additional @code{SIGALRM} signals from arriving in the | |
2650 | meantime by wrapping the critical part of the code with calls to | |
2651 | @code{sigprocmask}, like this: | |
2652 | ||
2653 | @smallexample | |
2654 | /* @r{This variable is set by the SIGALRM signal handler.} */ | |
2655 | volatile sig_atomic_t flag = 0; | |
2656 | ||
2657 | int | |
2658 | main (void) | |
2659 | @{ | |
2660 | sigset_t block_alarm; | |
2661 | ||
2662 | @dots{} | |
2663 | ||
2664 | /* @r{Initialize the signal mask.} */ | |
2665 | sigemptyset (&block_alarm); | |
2666 | sigaddset (&block_alarm, SIGALRM); | |
2667 | ||
2668 | @group | |
2669 | while (1) | |
2670 | @{ | |
2671 | /* @r{Check if a signal has arrived; if so, reset the flag.} */ | |
2672 | sigprocmask (SIG_BLOCK, &block_alarm, NULL); | |
2673 | if (flag) | |
2674 | @{ | |
2675 | @var{actions-if-not-arrived} | |
2676 | flag = 0; | |
2677 | @} | |
2678 | sigprocmask (SIG_UNBLOCK, &block_alarm, NULL); | |
2679 | ||
2680 | @dots{} | |
2681 | @} | |
2682 | @} | |
2683 | @end group | |
2684 | @end smallexample | |
2685 | ||
2686 | @node Blocking for Handler | |
2687 | @subsection Blocking Signals for a Handler | |
2688 | @cindex blocking signals, in a handler | |
2689 | ||
2690 | When a signal handler is invoked, you usually want it to be able to | |
2691 | finish without being interrupted by another signal. From the moment the | |
2692 | handler starts until the moment it finishes, you must block signals that | |
2693 | might confuse it or corrupt its data. | |
2694 | ||
2695 | When a handler function is invoked on a signal, that signal is | |
2696 | automatically blocked (in addition to any other signals that are already | |
2697 | in the process's signal mask) during the time the handler is running. | |
2698 | If you set up a handler for @code{SIGTSTP}, for instance, then the | |
2699 | arrival of that signal forces further @code{SIGTSTP} signals to wait | |
2700 | during the execution of the handler. | |
2701 | ||
2702 | However, by default, other kinds of signals are not blocked; they can | |
2703 | arrive during handler execution. | |
2704 | ||
2705 | The reliable way to block other kinds of signals during the execution of | |
2706 | the handler is to use the @code{sa_mask} member of the @code{sigaction} | |
2707 | structure. | |
2708 | ||
2709 | Here is an example: | |
2710 | ||
2711 | @smallexample | |
2712 | #include <signal.h> | |
2713 | #include <stddef.h> | |
2714 | ||
2715 | void catch_stop (); | |
2716 | ||
2717 | void | |
2718 | install_handler (void) | |
2719 | @{ | |
2720 | struct sigaction setup_action; | |
2721 | sigset_t block_mask; | |
2722 | ||
2723 | sigemptyset (&block_mask); | |
2724 | /* @r{Block other terminal-generated signals while handler runs.} */ | |
2725 | sigaddset (&block_mask, SIGINT); | |
2726 | sigaddset (&block_mask, SIGQUIT); | |
2727 | setup_action.sa_handler = catch_stop; | |
2728 | setup_action.sa_mask = block_mask; | |
2729 | setup_action.sa_flags = 0; | |
2730 | sigaction (SIGTSTP, &setup_action, NULL); | |
2731 | @} | |
2732 | @end smallexample | |
2733 | ||
2734 | This is more reliable than blocking the other signals explicitly in the | |
6d52618b | 2735 | code for the handler. If you block signals explicitly in the handler, |
28f540f4 RM |
2736 | you can't avoid at least a short interval at the beginning of the |
2737 | handler where they are not yet blocked. | |
2738 | ||
2739 | You cannot remove signals from the process's current mask using this | |
2740 | mechanism. However, you can make calls to @code{sigprocmask} within | |
2741 | your handler to block or unblock signals as you wish. | |
2742 | ||
2743 | In any case, when the handler returns, the system restores the mask that | |
2744 | was in place before the handler was entered. If any signals that become | |
2745 | unblocked by this restoration are pending, the process will receive | |
2746 | those signals immediately, before returning to the code that was | |
2747 | interrupted. | |
2748 | ||
2749 | @node Checking for Pending Signals | |
2750 | @subsection Checking for Pending Signals | |
2751 | @cindex pending signals, checking for | |
2752 | @cindex blocked signals, checking for | |
2753 | @cindex checking for pending signals | |
2754 | ||
2755 | You can find out which signals are pending at any time by calling | |
2756 | @code{sigpending}. This function is declared in @file{signal.h}. | |
2757 | @pindex signal.h | |
2758 | ||
2759 | @comment signal.h | |
2760 | @comment POSIX.1 | |
2761 | @deftypefun int sigpending (sigset_t *@var{set}) | |
2762 | The @code{sigpending} function stores information about pending signals | |
2763 | in @var{set}. If there is a pending signal that is blocked from | |
2764 | delivery, then that signal is a member of the returned set. (You can | |
2765 | test whether a particular signal is a member of this set using | |
2766 | @code{sigismember}; see @ref{Signal Sets}.) | |
2767 | ||
2768 | The return value is @code{0} if successful, and @code{-1} on failure. | |
2769 | @end deftypefun | |
2770 | ||
2771 | Testing whether a signal is pending is not often useful. Testing when | |
2772 | that signal is not blocked is almost certainly bad design. | |
2773 | ||
2774 | Here is an example. | |
2775 | ||
2776 | @smallexample | |
2777 | #include <signal.h> | |
2778 | #include <stddef.h> | |
2779 | ||
2780 | sigset_t base_mask, waiting_mask; | |
2781 | ||
2782 | sigemptyset (&base_mask); | |
2783 | sigaddset (&base_mask, SIGINT); | |
2784 | sigaddset (&base_mask, SIGTSTP); | |
2785 | ||
2786 | /* @r{Block user interrupts while doing other processing.} */ | |
f65fd747 | 2787 | sigprocmask (SIG_SETMASK, &base_mask, NULL); |
28f540f4 RM |
2788 | @dots{} |
2789 | ||
2790 | /* @r{After a while, check to see whether any signals are pending.} */ | |
2791 | sigpending (&waiting_mask); | |
2792 | if (sigismember (&waiting_mask, SIGINT)) @{ | |
2793 | /* @r{User has tried to kill the process.} */ | |
2794 | @} | |
2795 | else if (sigismember (&waiting_mask, SIGTSTP)) @{ | |
2796 | /* @r{User has tried to stop the process.} */ | |
2797 | @} | |
2798 | @end smallexample | |
2799 | ||
2800 | Remember that if there is a particular signal pending for your process, | |
2801 | additional signals of that same type that arrive in the meantime might | |
2802 | be discarded. For example, if a @code{SIGINT} signal is pending when | |
2803 | another @code{SIGINT} signal arrives, your program will probably only | |
2804 | see one of them when you unblock this signal. | |
2805 | ||
2806 | @strong{Portability Note:} The @code{sigpending} function is new in | |
2807 | POSIX.1. Older systems have no equivalent facility. | |
2808 | ||
2809 | @node Remembering a Signal | |
2810 | @subsection Remembering a Signal to Act On Later | |
2811 | ||
2812 | Instead of blocking a signal using the library facilities, you can get | |
2813 | almost the same results by making the handler set a flag to be tested | |
2814 | later, when you ``unblock''. Here is an example: | |
2815 | ||
2816 | @smallexample | |
2817 | /* @r{If this flag is nonzero, don't handle the signal right away.} */ | |
2818 | volatile sig_atomic_t signal_pending; | |
2819 | ||
2820 | /* @r{This is nonzero if a signal arrived and was not handled.} */ | |
2821 | volatile sig_atomic_t defer_signal; | |
2822 | ||
2823 | void | |
2824 | handler (int signum) | |
2825 | @{ | |
2826 | if (defer_signal) | |
2827 | signal_pending = signum; | |
2828 | else | |
2829 | @dots{} /* @r{``Really'' handle the signal.} */ | |
2830 | @} | |
2831 | ||
2832 | @dots{} | |
2833 | ||
2834 | void | |
2835 | update_mumble (int frob) | |
2836 | @{ | |
2837 | /* @r{Prevent signals from having immediate effect.} */ | |
2838 | defer_signal++; | |
2839 | /* @r{Now update @code{mumble}, without worrying about interruption.} */ | |
2840 | mumble.a = 1; | |
2841 | mumble.b = hack (); | |
2842 | mumble.c = frob; | |
2843 | /* @r{We have updated @code{mumble}. Handle any signal that came in.} */ | |
2844 | defer_signal--; | |
2845 | if (defer_signal == 0 && signal_pending != 0) | |
2846 | raise (signal_pending); | |
2847 | @} | |
2848 | @end smallexample | |
2849 | ||
2850 | Note how the particular signal that arrives is stored in | |
2851 | @code{signal_pending}. That way, we can handle several types of | |
2852 | inconvenient signals with the same mechanism. | |
2853 | ||
2854 | We increment and decrement @code{defer_signal} so that nested critical | |
2855 | sections will work properly; thus, if @code{update_mumble} were called | |
2856 | with @code{signal_pending} already nonzero, signals would be deferred | |
2857 | not only within @code{update_mumble}, but also within the caller. This | |
2858 | is also why we do not check @code{signal_pending} if @code{defer_signal} | |
2859 | is still nonzero. | |
2860 | ||
04b9968b | 2861 | The incrementing and decrementing of @code{defer_signal} each require more |
28f540f4 RM |
2862 | than one instruction; it is possible for a signal to happen in the |
2863 | middle. But that does not cause any problem. If the signal happens | |
2864 | early enough to see the value from before the increment or decrement, | |
2865 | that is equivalent to a signal which came before the beginning of the | |
2866 | increment or decrement, which is a case that works properly. | |
2867 | ||
2868 | It is absolutely vital to decrement @code{defer_signal} before testing | |
2869 | @code{signal_pending}, because this avoids a subtle bug. If we did | |
2870 | these things in the other order, like this, | |
2871 | ||
2872 | @smallexample | |
2873 | if (defer_signal == 1 && signal_pending != 0) | |
2874 | raise (signal_pending); | |
2875 | defer_signal--; | |
2876 | @end smallexample | |
2877 | ||
2878 | @noindent | |
2879 | then a signal arriving in between the @code{if} statement and the decrement | |
6d52618b | 2880 | would be effectively ``lost'' for an indefinite amount of time. The |
28f540f4 RM |
2881 | handler would merely set @code{defer_signal}, but the program having |
2882 | already tested this variable, it would not test the variable again. | |
2883 | ||
2884 | @cindex timing error in signal handling | |
2885 | Bugs like these are called @dfn{timing errors}. They are especially bad | |
2886 | because they happen only rarely and are nearly impossible to reproduce. | |
2887 | You can't expect to find them with a debugger as you would find a | |
2888 | reproducible bug. So it is worth being especially careful to avoid | |
2889 | them. | |
2890 | ||
2891 | (You would not be tempted to write the code in this order, given the use | |
2892 | of @code{defer_signal} as a counter which must be tested along with | |
2893 | @code{signal_pending}. After all, testing for zero is cleaner than | |
2894 | testing for one. But if you did not use @code{defer_signal} as a | |
2895 | counter, and gave it values of zero and one only, then either order | |
2896 | might seem equally simple. This is a further advantage of using a | |
2897 | counter for @code{defer_signal}: it will reduce the chance you will | |
2898 | write the code in the wrong order and create a subtle bug.) | |
2899 | ||
2900 | @node Waiting for a Signal | |
2901 | @section Waiting for a Signal | |
2902 | @cindex waiting for a signal | |
2903 | @cindex @code{pause} function | |
2904 | ||
2905 | If your program is driven by external events, or uses signals for | |
2906 | synchronization, then when it has nothing to do it should probably wait | |
2907 | until a signal arrives. | |
2908 | ||
2909 | @menu | |
2910 | * Using Pause:: The simple way, using @code{pause}. | |
2911 | * Pause Problems:: Why the simple way is often not very good. | |
2912 | * Sigsuspend:: Reliably waiting for a specific signal. | |
2913 | @end menu | |
2914 | ||
2915 | @node Using Pause | |
2916 | @subsection Using @code{pause} | |
2917 | ||
2918 | The simple way to wait until a signal arrives is to call @code{pause}. | |
2919 | Please read about its disadvantages, in the following section, before | |
2920 | you use it. | |
2921 | ||
2922 | @comment unistd.h | |
2923 | @comment POSIX.1 | |
8ded91fb | 2924 | @deftypefun int pause (void) |
28f540f4 RM |
2925 | The @code{pause} function suspends program execution until a signal |
2926 | arrives whose action is either to execute a handler function, or to | |
2927 | terminate the process. | |
2928 | ||
2929 | If the signal causes a handler function to be executed, then | |
2930 | @code{pause} returns. This is considered an unsuccessful return (since | |
2931 | ``successful'' behavior would be to suspend the program forever), so the | |
2932 | return value is @code{-1}. Even if you specify that other primitives | |
2933 | should resume when a system handler returns (@pxref{Interrupted | |
2934 | Primitives}), this has no effect on @code{pause}; it always fails when a | |
2935 | signal is handled. | |
2936 | ||
2937 | The following @code{errno} error conditions are defined for this function: | |
2938 | ||
2939 | @table @code | |
2940 | @item EINTR | |
2941 | The function was interrupted by delivery of a signal. | |
2942 | @end table | |
2943 | ||
2944 | If the signal causes program termination, @code{pause} doesn't return | |
2945 | (obviously). | |
2946 | ||
04b9968b | 2947 | This function is a cancellation point in multithreaded programs. This |
dfd2257a UD |
2948 | is a problem if the thread allocates some resources (like memory, file |
2949 | descriptors, semaphores or whatever) at the time @code{pause} is | |
04b9968b | 2950 | called. If the thread gets cancelled these resources stay allocated |
dfd2257a | 2951 | until the program ends. To avoid this calls to @code{pause} should be |
04b9968b | 2952 | protected using cancellation handlers. |
dfd2257a UD |
2953 | @c ref pthread_cleanup_push / pthread_cleanup_pop |
2954 | ||
28f540f4 RM |
2955 | The @code{pause} function is declared in @file{unistd.h}. |
2956 | @end deftypefun | |
2957 | ||
2958 | @node Pause Problems | |
2959 | @subsection Problems with @code{pause} | |
2960 | ||
2961 | The simplicity of @code{pause} can conceal serious timing errors that | |
2962 | can make a program hang mysteriously. | |
2963 | ||
2964 | It is safe to use @code{pause} if the real work of your program is done | |
2965 | by the signal handlers themselves, and the ``main program'' does nothing | |
2966 | but call @code{pause}. Each time a signal is delivered, the handler | |
2967 | will do the next batch of work that is to be done, and then return, so | |
2968 | that the main loop of the program can call @code{pause} again. | |
2969 | ||
2970 | You can't safely use @code{pause} to wait until one more signal arrives, | |
2971 | and then resume real work. Even if you arrange for the signal handler | |
2972 | to cooperate by setting a flag, you still can't use @code{pause} | |
2973 | reliably. Here is an example of this problem: | |
2974 | ||
2975 | @smallexample | |
2976 | /* @r{@code{usr_interrupt} is set by the signal handler.} */ | |
2977 | if (!usr_interrupt) | |
2978 | pause (); | |
2979 | ||
2980 | /* @r{Do work once the signal arrives.} */ | |
2981 | @dots{} | |
2982 | @end smallexample | |
2983 | ||
2984 | @noindent | |
2985 | This has a bug: the signal could arrive after the variable | |
2986 | @code{usr_interrupt} is checked, but before the call to @code{pause}. | |
2987 | If no further signals arrive, the process would never wake up again. | |
2988 | ||
2989 | You can put an upper limit on the excess waiting by using @code{sleep} | |
2990 | in a loop, instead of using @code{pause}. (@xref{Sleeping}, for more | |
2991 | about @code{sleep}.) Here is what this looks like: | |
2992 | ||
2993 | @smallexample | |
2994 | /* @r{@code{usr_interrupt} is set by the signal handler.} | |
2995 | while (!usr_interrupt) | |
2996 | sleep (1); | |
2997 | ||
2998 | /* @r{Do work once the signal arrives.} */ | |
2999 | @dots{} | |
3000 | @end smallexample | |
3001 | ||
3002 | For some purposes, that is good enough. But with a little more | |
3003 | complexity, you can wait reliably until a particular signal handler is | |
3004 | run, using @code{sigsuspend}. | |
3005 | @ifinfo | |
3006 | @xref{Sigsuspend}. | |
3007 | @end ifinfo | |
3008 | ||
3009 | @node Sigsuspend | |
3010 | @subsection Using @code{sigsuspend} | |
3011 | ||
3012 | The clean and reliable way to wait for a signal to arrive is to block it | |
3013 | and then use @code{sigsuspend}. By using @code{sigsuspend} in a loop, | |
3014 | you can wait for certain kinds of signals, while letting other kinds of | |
3015 | signals be handled by their handlers. | |
3016 | ||
3017 | @comment signal.h | |
3018 | @comment POSIX.1 | |
3019 | @deftypefun int sigsuspend (const sigset_t *@var{set}) | |
3020 | This function replaces the process's signal mask with @var{set} and then | |
3021 | suspends the process until a signal is delivered whose action is either | |
3022 | to terminate the process or invoke a signal handling function. In other | |
3023 | words, the program is effectively suspended until one of the signals that | |
3024 | is not a member of @var{set} arrives. | |
3025 | ||
a496e4ce | 3026 | If the process is woken up by delivery of a signal that invokes a handler |
28f540f4 RM |
3027 | function, and the handler function returns, then @code{sigsuspend} also |
3028 | returns. | |
3029 | ||
3030 | The mask remains @var{set} only as long as @code{sigsuspend} is waiting. | |
3031 | The function @code{sigsuspend} always restores the previous signal mask | |
f65fd747 | 3032 | when it returns. |
28f540f4 RM |
3033 | |
3034 | The return value and error conditions are the same as for @code{pause}. | |
3035 | @end deftypefun | |
3036 | ||
3037 | With @code{sigsuspend}, you can replace the @code{pause} or @code{sleep} | |
3038 | loop in the previous section with something completely reliable: | |
3039 | ||
3040 | @smallexample | |
3041 | sigset_t mask, oldmask; | |
3042 | ||
3043 | @dots{} | |
3044 | ||
f65fd747 UD |
3045 | /* @r{Set up the mask of signals to temporarily block.} */ |
3046 | sigemptyset (&mask); | |
28f540f4 RM |
3047 | sigaddset (&mask, SIGUSR1); |
3048 | ||
3049 | @dots{} | |
3050 | ||
3051 | /* @r{Wait for a signal to arrive.} */ | |
3052 | sigprocmask (SIG_BLOCK, &mask, &oldmask); | |
3053 | while (!usr_interrupt) | |
3054 | sigsuspend (&oldmask); | |
3055 | sigprocmask (SIG_UNBLOCK, &mask, NULL); | |
3056 | @end smallexample | |
3057 | ||
3058 | This last piece of code is a little tricky. The key point to remember | |
3059 | here is that when @code{sigsuspend} returns, it resets the process's | |
3060 | signal mask to the original value, the value from before the call to | |
3061 | @code{sigsuspend}---in this case, the @code{SIGUSR1} signal is once | |
3062 | again blocked. The second call to @code{sigprocmask} is | |
3063 | necessary to explicitly unblock this signal. | |
3064 | ||
3065 | One other point: you may be wondering why the @code{while} loop is | |
3066 | necessary at all, since the program is apparently only waiting for one | |
3067 | @code{SIGUSR1} signal. The answer is that the mask passed to | |
3068 | @code{sigsuspend} permits the process to be woken up by the delivery of | |
3069 | other kinds of signals, as well---for example, job control signals. If | |
3070 | the process is woken up by a signal that doesn't set | |
3071 | @code{usr_interrupt}, it just suspends itself again until the ``right'' | |
3072 | kind of signal eventually arrives. | |
3073 | ||
3074 | This technique takes a few more lines of preparation, but that is needed | |
3075 | just once for each kind of wait criterion you want to use. The code | |
3076 | that actually waits is just four lines. | |
3077 | ||
3078 | @node Signal Stack | |
3079 | @section Using a Separate Signal Stack | |
3080 | ||
3081 | A signal stack is a special area of memory to be used as the execution | |
3082 | stack during signal handlers. It should be fairly large, to avoid any | |
3083 | danger that it will overflow in turn; the macro @code{SIGSTKSZ} is | |
3084 | defined to a canonical size for signal stacks. You can use | |
3085 | @code{malloc} to allocate the space for the stack. Then call | |
3086 | @code{sigaltstack} or @code{sigstack} to tell the system to use that | |
3087 | space for the signal stack. | |
3088 | ||
3089 | You don't need to write signal handlers differently in order to use a | |
3090 | signal stack. Switching from one stack to the other happens | |
3091 | automatically. (Some non-GNU debuggers on some machines may get | |
3092 | confused if you examine a stack trace while a handler that uses the | |
3093 | signal stack is running.) | |
3094 | ||
3095 | There are two interfaces for telling the system to use a separate signal | |
3096 | stack. @code{sigstack} is the older interface, which comes from 4.2 | |
3097 | BSD. @code{sigaltstack} is the newer interface, and comes from 4.4 | |
3098 | BSD. The @code{sigaltstack} interface has the advantage that it does | |
3099 | not require your program to know which direction the stack grows, which | |
3100 | depends on the specific machine and operating system. | |
3101 | ||
3102 | @comment signal.h | |
eacde9d0 UD |
3103 | @comment XPG |
3104 | @deftp {Data Type} stack_t | |
28f540f4 RM |
3105 | This structure describes a signal stack. It contains the following members: |
3106 | ||
3107 | @table @code | |
3108 | @item void *ss_sp | |
3109 | This points to the base of the signal stack. | |
3110 | ||
3111 | @item size_t ss_size | |
3112 | This is the size (in bytes) of the signal stack which @samp{ss_sp} points to. | |
3113 | You should set this to however much space you allocated for the stack. | |
3114 | ||
3115 | There are two macros defined in @file{signal.h} that you should use in | |
3116 | calculating this size: | |
3117 | ||
3118 | @vtable @code | |
3119 | @item SIGSTKSZ | |
3120 | This is the canonical size for a signal stack. It is judged to be | |
3121 | sufficient for normal uses. | |
3122 | ||
3123 | @item MINSIGSTKSZ | |
3124 | This is the amount of signal stack space the operating system needs just | |
3125 | to implement signal delivery. The size of a signal stack @strong{must} | |
3126 | be greater than this. | |
3127 | ||
3128 | For most cases, just using @code{SIGSTKSZ} for @code{ss_size} is | |
3129 | sufficient. But if you know how much stack space your program's signal | |
3130 | handlers will need, you may want to use a different size. In this case, | |
3131 | you should allocate @code{MINSIGSTKSZ} additional bytes for the signal | |
6d52618b | 3132 | stack and increase @code{ss_size} accordingly. |
28f540f4 RM |
3133 | @end vtable |
3134 | ||
3135 | @item int ss_flags | |
3136 | This field contains the bitwise @sc{or} of these flags: | |
3137 | ||
3138 | @vtable @code | |
7ce241a0 | 3139 | @item SS_DISABLE |
28f540f4 RM |
3140 | This tells the system that it should not use the signal stack. |
3141 | ||
7ce241a0 | 3142 | @item SS_ONSTACK |
28f540f4 RM |
3143 | This is set by the system, and indicates that the signal stack is |
3144 | currently in use. If this bit is not set, then signals will be | |
3145 | delivered on the normal user stack. | |
3146 | @end vtable | |
3147 | @end table | |
3148 | @end deftp | |
3149 | ||
3150 | @comment signal.h | |
eacde9d0 UD |
3151 | @comment XPG |
3152 | @deftypefun int sigaltstack (const stack_t *restrict @var{stack}, stack_t *restrict @var{oldstack}) | |
28f540f4 RM |
3153 | The @code{sigaltstack} function specifies an alternate stack for use |
3154 | during signal handling. When a signal is received by the process and | |
3155 | its action indicates that the signal stack is used, the system arranges | |
3156 | a switch to the currently installed signal stack while the handler for | |
3157 | that signal is executed. | |
3158 | ||
3159 | If @var{oldstack} is not a null pointer, information about the currently | |
3160 | installed signal stack is returned in the location it points to. If | |
3161 | @var{stack} is not a null pointer, then this is installed as the new | |
3162 | stack for use by signal handlers. | |
3163 | ||
3164 | The return value is @code{0} on success and @code{-1} on failure. If | |
3165 | @code{sigaltstack} fails, it sets @code{errno} to one of these values: | |
3166 | ||
3167 | @table @code | |
28f540f4 RM |
3168 | @item EINVAL |
3169 | You tried to disable a stack that was in fact currently in use. | |
3170 | ||
3171 | @item ENOMEM | |
f65fd747 | 3172 | The size of the alternate stack was too small. |
28f540f4 RM |
3173 | It must be greater than @code{MINSIGSTKSZ}. |
3174 | @end table | |
3175 | @end deftypefun | |
3176 | ||
3177 | Here is the older @code{sigstack} interface. You should use | |
3178 | @code{sigaltstack} instead on systems that have it. | |
3179 | ||
3180 | @comment signal.h | |
3181 | @comment BSD | |
3182 | @deftp {Data Type} {struct sigstack} | |
3183 | This structure describes a signal stack. It contains the following members: | |
3184 | ||
3185 | @table @code | |
3186 | @item void *ss_sp | |
3187 | This is the stack pointer. If the stack grows downwards on your | |
3188 | machine, this should point to the top of the area you allocated. If the | |
3189 | stack grows upwards, it should point to the bottom. | |
3190 | ||
3191 | @item int ss_onstack | |
3192 | This field is true if the process is currently using this stack. | |
3193 | @end table | |
3194 | @end deftp | |
3195 | ||
3196 | @comment signal.h | |
3197 | @comment BSD | |
8ded91fb | 3198 | @deftypefun int sigstack (struct sigstack *@var{stack}, struct sigstack *@var{oldstack}) |
28f540f4 RM |
3199 | The @code{sigstack} function specifies an alternate stack for use during |
3200 | signal handling. When a signal is received by the process and its | |
3201 | action indicates that the signal stack is used, the system arranges a | |
3202 | switch to the currently installed signal stack while the handler for | |
3203 | that signal is executed. | |
3204 | ||
3205 | If @var{oldstack} is not a null pointer, information about the currently | |
3206 | installed signal stack is returned in the location it points to. If | |
3207 | @var{stack} is not a null pointer, then this is installed as the new | |
3208 | stack for use by signal handlers. | |
3209 | ||
3210 | The return value is @code{0} on success and @code{-1} on failure. | |
3211 | @end deftypefun | |
3212 | ||
3213 | @node BSD Signal Handling | |
3214 | @section BSD Signal Handling | |
3215 | ||
3216 | This section describes alternative signal handling functions derived | |
3217 | from BSD Unix. These facilities were an advance, in their time; today, | |
3218 | they are mostly obsolete, and supported mainly for compatibility with | |
3219 | BSD Unix. | |
3220 | ||
3221 | There are many similarities between the BSD and POSIX signal handling | |
3222 | facilities, because the POSIX facilities were inspired by the BSD | |
3223 | facilities. Besides having different names for all the functions to | |
3224 | avoid conflicts, the main differences between the two are: | |
3225 | ||
3226 | @itemize @bullet | |
3227 | @item | |
3228 | BSD Unix represents signal masks as an @code{int} bit mask, rather than | |
3229 | as a @code{sigset_t} object. | |
3230 | ||
3231 | @item | |
3232 | The BSD facilities use a different default for whether an interrupted | |
3233 | primitive should fail or resume. The POSIX facilities make system | |
3234 | calls fail unless you specify that they should resume. With the BSD | |
3235 | facility, the default is to make system calls resume unless you say they | |
3236 | should fail. @xref{Interrupted Primitives}. | |
3237 | @end itemize | |
3238 | ||
3239 | The BSD facilities are declared in @file{signal.h}. | |
3240 | @pindex signal.h | |
3241 | ||
3242 | @menu | |
3243 | * BSD Handler:: BSD Function to Establish a Handler. | |
f65fd747 | 3244 | * Blocking in BSD:: BSD Functions for Blocking Signals. |
28f540f4 RM |
3245 | @end menu |
3246 | ||
3247 | @node BSD Handler | |
3248 | @subsection BSD Function to Establish a Handler | |
3249 | ||
3250 | @comment signal.h | |
3251 | @comment BSD | |
3252 | @deftp {Data Type} {struct sigvec} | |
3253 | This data type is the BSD equivalent of @code{struct sigaction} | |
3254 | (@pxref{Advanced Signal Handling}); it is used to specify signal actions | |
3255 | to the @code{sigvec} function. It contains the following members: | |
3256 | ||
3257 | @table @code | |
3258 | @item sighandler_t sv_handler | |
3259 | This is the handler function. | |
3260 | ||
3261 | @item int sv_mask | |
3262 | This is the mask of additional signals to be blocked while the handler | |
3263 | function is being called. | |
3264 | ||
3265 | @item int sv_flags | |
3266 | This is a bit mask used to specify various flags which affect the | |
3267 | behavior of the signal. You can also refer to this field as | |
3268 | @code{sv_onstack}. | |
3269 | @end table | |
3270 | @end deftp | |
3271 | ||
3272 | These symbolic constants can be used to provide values for the | |
3273 | @code{sv_flags} field of a @code{sigvec} structure. This field is a bit | |
3274 | mask value, so you bitwise-OR the flags of interest to you together. | |
3275 | ||
3276 | @comment signal.h | |
3277 | @comment BSD | |
3278 | @deftypevr Macro int SV_ONSTACK | |
3279 | If this bit is set in the @code{sv_flags} field of a @code{sigvec} | |
3280 | structure, it means to use the signal stack when delivering the signal. | |
3281 | @end deftypevr | |
3282 | ||
3283 | @comment signal.h | |
3284 | @comment BSD | |
3285 | @deftypevr Macro int SV_INTERRUPT | |
3286 | If this bit is set in the @code{sv_flags} field of a @code{sigvec} | |
3287 | structure, it means that system calls interrupted by this kind of signal | |
3288 | should not be restarted if the handler returns; instead, the system | |
3289 | calls should return with a @code{EINTR} error status. @xref{Interrupted | |
3290 | Primitives}. | |
3291 | @end deftypevr | |
3292 | ||
3293 | @comment signal.h | |
3294 | @comment Sun | |
3295 | @deftypevr Macro int SV_RESETHAND | |
3296 | If this bit is set in the @code{sv_flags} field of a @code{sigvec} | |
3297 | structure, it means to reset the action for the signal back to | |
3298 | @code{SIG_DFL} when the signal is received. | |
3299 | @end deftypevr | |
3300 | ||
3301 | @comment signal.h | |
3302 | @comment BSD | |
cc6e48bc | 3303 | @deftypefun int sigvec (int @var{signum}, const struct sigvec *@var{action}, struct sigvec *@var{old-action}) |
28f540f4 RM |
3304 | This function is the equivalent of @code{sigaction} (@pxref{Advanced Signal |
3305 | Handling}); it installs the action @var{action} for the signal @var{signum}, | |
3306 | returning information about the previous action in effect for that signal | |
3307 | in @var{old-action}. | |
3308 | @end deftypefun | |
3309 | ||
3310 | @comment signal.h | |
3311 | @comment BSD | |
3312 | @deftypefun int siginterrupt (int @var{signum}, int @var{failflag}) | |
3313 | This function specifies which approach to use when certain primitives | |
3314 | are interrupted by handling signal @var{signum}. If @var{failflag} is | |
3315 | false, signal @var{signum} restarts primitives. If @var{failflag} is | |
3316 | true, handling @var{signum} causes these primitives to fail with error | |
3317 | code @code{EINTR}. @xref{Interrupted Primitives}. | |
3318 | @end deftypefun | |
3319 | ||
3320 | @node Blocking in BSD | |
f65fd747 | 3321 | @subsection BSD Functions for Blocking Signals |
28f540f4 RM |
3322 | |
3323 | @comment signal.h | |
3324 | @comment BSD | |
3325 | @deftypefn Macro int sigmask (int @var{signum}) | |
3326 | This macro returns a signal mask that has the bit for signal @var{signum} | |
3327 | set. You can bitwise-OR the results of several calls to @code{sigmask} | |
3328 | together to specify more than one signal. For example, | |
3329 | ||
3330 | @smallexample | |
3331 | (sigmask (SIGTSTP) | sigmask (SIGSTOP) | |
3332 | | sigmask (SIGTTIN) | sigmask (SIGTTOU)) | |
3333 | @end smallexample | |
3334 | ||
3335 | @noindent | |
3336 | specifies a mask that includes all the job-control stop signals. | |
3337 | @end deftypefn | |
3338 | ||
3339 | @comment signal.h | |
3340 | @comment BSD | |
3341 | @deftypefun int sigblock (int @var{mask}) | |
3342 | This function is equivalent to @code{sigprocmask} (@pxref{Process Signal | |
3343 | Mask}) with a @var{how} argument of @code{SIG_BLOCK}: it adds the | |
3344 | signals specified by @var{mask} to the calling process's set of blocked | |
3345 | signals. The return value is the previous set of blocked signals. | |
3346 | @end deftypefun | |
3347 | ||
3348 | @comment signal.h | |
3349 | @comment BSD | |
3350 | @deftypefun int sigsetmask (int @var{mask}) | |
3351 | This function equivalent to @code{sigprocmask} (@pxref{Process | |
3352 | Signal Mask}) with a @var{how} argument of @code{SIG_SETMASK}: it sets | |
3353 | the calling process's signal mask to @var{mask}. The return value is | |
3354 | the previous set of blocked signals. | |
3355 | @end deftypefun | |
3356 | ||
3357 | @comment signal.h | |
3358 | @comment BSD | |
3359 | @deftypefun int sigpause (int @var{mask}) | |
3360 | This function is the equivalent of @code{sigsuspend} (@pxref{Waiting | |
3361 | for a Signal}): it sets the calling process's signal mask to @var{mask}, | |
3362 | and waits for a signal to arrive. On return the previous set of blocked | |
3363 | signals is restored. | |
3364 | @end deftypefun |