Put a @table around @include summary.out.
[kopensolaris-gnu/glibc.git] / manual / signal.texi
1 @node Signal Handling
2 @chapter Signal Handling
3
4 @cindex signal
5 A @dfn{signal} can be considered a software interrupt.  They are used by
6 the operating system to report information about exceptional situations
7 to an executing program.
8
9 The GNU C library defines a variety of signal types to handle program
10 errors and other system events that affect the behavior of your program.
11 Most of these events make it inadvisable or impossible for the program
12 to proceed as usual, and therefore normally cause the kernel to abort
13 the program.
14
15 If you can anticipate the events that cause signals, you can trap them
16 and override their default effects.  You can write a signal handler and
17 tell the operating system to run it when a particular type of signal
18 arrives.  Finally, you can send a signal to another process; this allows
19 parent process to abort a child, or two related processes to communicate
20 and synchronize.
21
22 @menu
23 * Signal Concepts::             Introduction to the signal facilities.
24 * Signal Names::                What the standard signals are and when
25                                  they happen.
26 * Specifying Signal Actions::   How to override the default behavior
27                                  for a signal.
28 * Defining a Signal Handler::   How to write a signal handler function.
29 * Generating Signals::          How to send a signal to a process.
30 * Blocking Signals::            Making the system hold signals temporarily.
31 * Waiting for a Signal::        Suspending your program until a signal arrives.
32 * BSD Signal Handling::         Additional functions for backward
33                                  compatibility with BSD.
34 @end menu
35
36
37 @node Signal Concepts
38 @section Signal Concepts
39
40 Common events that generate signals include:
41
42 @itemize @bullet
43 @item
44 A program error such as dividing by zero or issuing an address outside
45 the valid range.
46
47 @item
48 A user request to interrupt or terminate the program.  Most environments
49 are set up to let a user suspend the program by typing @kbd{C-z}, or
50 terminate it with @kbd{C-c}.  Whatever key sequence is used, the
51 operating system sends the proper signal to interrupt the process.
52
53 @item
54 The termination of a child process.
55
56 @item
57 A @code{kill} call from another process.  Signals are a limited but
58 useful form of interprocess communication.
59
60 @item
61 Expiration of a timer or alarm.
62 @end itemize
63
64 There are different kinds of signals defined to indicate each of these
65 situations.  These are described in more detail in @ref{Signal Names}.
66
67 You can tell the process to ignore the signal, or tell it to call a
68 function you provide when the signal is delivered.  In the latter case,
69 it is said that the signal is @dfn{trapped} or @dfn{caught} by the
70 handler.  For more details about how to specify actions to take when a
71 signal arrives, @pxref{Specifying Signal Actions}.  
72 @cindex trapping signals
73 @cindex catching signals
74
75 The default action taken by a process when it receives most signals is
76 to terminate the process.  When this happens, its parent process can
77 detect the situation by examining the termination status code reported
78 by the @code{wait} or @code{waitpid} functions.  (This is discussed in
79 more detail in @ref{Process Completion}.)  If a program you run from a
80 shell is terminated by a signal, the shell typically provides some kind
81 of error message.
82
83 When a signal is @dfn{generated}, it is normally @dfn{delivered} to the
84 process immediately.  However, you can @dfn{block} or delay delivery of
85 signals.  If the action for a particular signal is something other than
86 to ignore it, when a signal of that type is generated it remains
87 @dfn{pending} until it is either unblocked (in which case it will be
88 delivered to the process) or its action is set to be ignored (causing it
89 to be discarded).  Signals that are ignored may be discarded immediately
90 if they are blocked.  The facilities for controlling blocking of signals
91 are discussed in @ref{Blocking Signals}.
92 @cindex generation of signals
93 @cindex delivery of signals
94 @cindex pending signals
95 @cindex blocked signals
96
97 @node Signal Names
98 @section Signal Names
99 @cindex signal names
100
101 Symbolic names for the various kinds of signals are defined in the
102 header file @file{signal.h}.  Each is a macro wich standars for a
103 positive integer.  This section describes what conditions these signals
104 are used for.
105 @pindex signal.h
106
107 @comment signal.h
108 @comment GNU
109 @deftypevr Macro int NSIG
110 The value of this symbolic constant is the total number of signals
111 defined.
112 @end deftypevr
113
114 @menu
115 * Program Error Signals::       Used to report serious program errors.
116 * Termination Signals::         Used to interrupt and/or terminate the program.
117 * Alarm Signals::               Used to indicate expiration of timers.
118 * Asynchronous I/O Signals::    Used to indicate input is available.
119 * Miscellanous Signals::        Used to report various random conditions.
120 * Job Control Signals::         Signals used to support job control.
121 * Other Signals::               Implementations can support other signals.
122 * Signal Messages::             Printing a message describing a signal.
123 @end menu
124
125 @node Program Error Signals
126 @subsection Program Error Signals
127 @cindex program error signals
128
129 The following signals are generated when a serious program error is
130 detected by the operating system or the computer itself.  In general,
131 all of these signals are indications that your program is seriously
132 broken in some way, and there's usually not much you can do to recover
133 from these conditions.
134
135 The default action for all of these signals is to cause the process to
136 terminate.  If you block or ignore these signals or establish a handler
137 for them that returns normally, your program will probably break
138 horribly unless the signals were generated by @code{raise} or
139 @code{kill} instead of a real program bug.
140
141 @comment signal.h
142 @comment ANSI
143 @deftypevr Macro int SIGFPE
144 The @code{SIGFPE} signal reports a fatal arithmetic error.  Although the
145 name is derived from ``floating-point exception'', this signal actually
146 covers all arithmetic errors, including division by zero and overflow.
147 If your program gets mixed up and stores integer data in a location
148 which is then used in a floating-point operation, you often get an
149 ``invalid operation'' exception, because the processor cannot recognize
150 the data as a floating-point number.
151 @cindex exception
152 @cindex floating-point exception
153
154 Floating-point exceptions are a complicated subject because there are
155 many types of exceptions with subtly different meanings, and the
156 @code{SIGFPE} signal doesn't distinguish between them.  The @cite{IEEE
157 Standard for Binary Floating-Point Arithmetic (ANSI/IEEE Std 754-1985)}
158 defines various floating-point exceptions and requires conforming
159 computer systems to report their occurrences.  However, this standard
160 does not specify how the exceptions are reported, or what kinds of
161 handling and control the operating system can offer to the programmer.
162 If you're writing a library of numeric routines that has to be able to
163 trap and deal with the different kinds of exceptions intelligently,
164 you'll have to look at the documentation for your specific computer and
165 operating system to find out how.
166 @end deftypevr
167
168 @comment signal.h
169 @comment ANSI
170 @deftypevr Macro int SIGILL
171 The name of this signal is derived from ``illegal instruction''; it
172 means your program is trying to execute garbage or a privileged
173 instruction.  In a C program, this typically indicates that the
174 executable file is corrupted, or that you are trying to execute data.
175 Some common ways of getting into the latter situation are by passing an
176 invalid object where a pointer to a function was expected, or by writing
177 past the end of an automatic array (or similar problems with pointers to
178 automatic variables) and corrupting control information on the stack,
179 like a return address from a function call.
180 @end deftypevr
181 @cindex illegal instruction
182
183 @comment signal.h
184 @comment ANSI
185 @deftypevr Macro int SIGSEGV
186 This signal is generated when a program tries to read or write outside
187 the memory that is allocated for it.  (Actually, the signals only occur
188 when the program goes far enough outside to be detected by the system's
189 memory protection mechanism.)  The name is an abbreviation for ``segmentation
190 violation''.
191
192 The most common way of getting a @code{SIGSEGV} condition is by
193 dereferencing a null or uninitialized pointer.  Another typical way of
194 getting into a @code{SIGSEGV} situation is when you use a pointer to
195 step through an array, but fail to check for the end of the array.
196 @end deftypevr
197 @cindex segmentation violation
198
199 @comment signal.h
200 @comment BSD
201 @deftypevr Macro int SIGBUS
202 This signal is generated when an invalid pointer is dereferenced.  Like
203 @code{SIGSEGV}, this signal is typically the result of dereferencing an
204 uninitialized pointer.  The difference between the two is that
205 @code{SIGSEGV} indicates an invalid access to valid memory, while
206 @code{SIGBUS} indicates an access to an invalid address.  In particular,
207 @code{SIGBUS} signals often result from dereferencing a misaligned
208 pointer.
209
210 The name of this signal is an abbreviation for ``bus error''.
211 @end deftypevr
212 @cindex bus error
213
214
215 @node Termination Signals
216 @subsection Termination Signals
217 @cindex program termination signals
218
219 These signals are all used to tell a process to terminate, in one way
220 or another.  They have different names because they're used for slightly
221 different purposes, and you might want to establish different actions
222 for each one.
223
224 The (obvious) default action for all of these signals is to cause the
225 process to terminate.
226
227 @comment RMS was confused and thought SIGABRT was the same as SIGILL,
228 @comment and wanted its description moved into the previous node.  But
229 @comment is *not* the same as SIGILL -- it's the same as SIGIOT, which
230 @comment is one of those hardware-specific signals we don't discuss in
231 @comment detail.  So I've left SIGABRT here.
232
233 @comment signal.h
234 @comment ANSI
235 @deftypevr Macro int SIGABRT
236 This signal indicates an error detected by the program itself, which
237 causes abnormal program termination.  The @code{abort} function
238 (@xref{Aborting a Program}) generates this signal.
239 @end deftypevr
240 @cindex abort signal
241
242 @comment signal.h
243 @comment POSIX.1
244 @deftypevr Macro int SIGHUP
245 The @code{SIGHUP} (``hang-up'') signal is used to report that the user's
246 terminal is disconnected, perhaps because a network or telephone
247 connection was broken.  For more information about this, @pxref{Control
248 Modes}.
249
250 This signal is also used to report the termination of the controlling
251 process on a terminal to jobs associated with that session; in effect,
252 this reports that a process has been disconnected from its controlling
253 terminal.  For more information, @pxref{Process Termination Details}.
254 @end deftypevr
255 @cindex hangup signal
256
257 @comment signal.h
258 @comment ANSI
259 @deftypevr Macro int SIGINT
260 The @code{SIGINT} (``program interrupt'') signal is sent when the user
261 types the INTR character (normally @kbd{C-c}).  @xref{Special
262 Characters}, for information about terminal driver support.
263
264 You might want to establish a handler for this signal in order to make
265 your program terminate cleanly, performing whatever tidying-up actions
266 are appropriate first.  For example, you might want to write out state
267 information to a file, release locks on resources, and the like.
268 @end deftypevr
269 @cindex interrupt signal
270
271 @comment signal.h
272 @comment POSIX.1
273 @deftypevr Macro int SIGQUIT
274 The @code{SIGQUIT} signal is similar to @code{SIGINT}, except that it's
275 controlled by a different key --- the QUIT character, usually @kbd{C-\}
276 --- and produces a core dump when it terminates the process.
277 @xref{Special Characters}, for information about terminal driver
278 support.
279 @end deftypevr
280 @cindex quit signal
281
282 @comment signal.h
283 @comment POSIX.1
284 @deftypevr Macro int SIGKILL
285 The @code{SIGKILL} signal is used to cause immediate program termination.
286 It cannot be caught or ignored, and is therefore always fatal.  It is
287 also not possible to block this signal.
288
289 This signal occurs only on explicit request by a user program.  You would
290 use it when you want to immediately terminate a program.  For example, if
291 a process is not responding to any other termination signals, sending it
292 a @code{SIGKILL} signal will almost always cause it to go away.
293 @end deftypevr
294 @cindex kill signal
295
296 @comment signal.h
297 @comment ANSI
298 @deftypevr Macro int SIGTERM
299 The @code{SIGTERM} signal is a generic signal used to cause program
300 termination.  Unlike @code{SIGKILL}, this signal can be blocked, caught,
301 or ignored.
302
303 The shell command @code{kill} generates @code{SIGTERM} by default.
304 @pindex kill
305 @end deftypevr
306 @cindex termination signal
307
308
309 @node Alarm Signals
310 @subsection Alarm Signals
311
312 These signals are used to indicate the expiration of timers.
313 @xref{Setting an Alarm}, for information about functions that cause
314 these signals to be sent.
315
316 The default behavior for these signals is to cause program termination
317 --- not a very useful default, but we are stuck with it.  If you want to
318 use these signals, you should normally provide a signal handler.
319
320 @comment signal.h
321 @comment POSIX.1
322 @deftypevr Macro int SIGALRM
323 This signal typically indicates expiration of a timer that
324 measures real or clock time.  It is used by the @code{alarm} function,
325 for example.
326 @end deftypevr
327 @cindex alarm signal
328
329 @comment signal.h
330 @comment BSD
331 @deftypevr Macro int SIGVTALRM
332 This signal typically indicates expiration of a timer that measures CPU
333 time used by the current process.  The name is an abbreviation for
334 ``virtual time alarm''.
335 @end deftypevr
336 @cindex virtual time alarm signal
337
338 @comment signal.h
339 @comment BSD
340 @deftypevr Macro int SIGPROF
341 This signal is typically indicates expiration of a timer that measures
342 both CPU time used by the current process, and CPU time expended on 
343 behalf of the process by the system.  Such a timer is used to implement
344 code profiling facilities, hence the name of this signal.
345 @end deftypevr
346 @cindex profiling alarm signal
347
348
349 @node Asynchronous I/O Signals
350 @subsection Asynchronous I/O Signals
351
352 The signals listed in this section are used in conjunction with
353 asynchronous I/O facilities.  You have to take explicit action by
354 calling @code{fcntl} to enable delivery of these signals by the
355 operating system; @pxref{Interrupt Input}.  The default action for these
356 signals is to ignore them.
357
358 @comment signal.h
359 @comment BSD
360 @deftypevr Macro int SIGIO
361 This signal is sent when a file descriptor is ready to perform input
362 or output.
363 @end deftypevr
364 @cindex input/output signal
365
366 @comment signal.h
367 @comment BSD
368 @deftypevr Macro int SIGURG
369 This signal is sent when ``urgent'' or out-of-band data arrives on a
370 socket.  @xref{Out-of-Band Data}.
371 @end deftypevr
372 @cindex urgent data signal
373
374
375 @node Miscellaneous Signals
376 @subsection Miscellaneous Signals
377
378 These signals are used to report various other conditions.  The default
379 action for all of them is to cause the process to terminate.
380
381 @comment signal.h
382 @comment POSIX.1
383 @deftypevr Macro int SIGPIPE
384 If you use pipes or FIFO special files, you have to design your
385 application so that one process opens the pipe for reading before
386 another starts writing.  If the reading process never starts, or
387 terminates unexpectedly, a write to the pipe or FIFO causes the writing
388 process to receive a @code{SIGPIPE} signal.
389
390 Pipes and FIFO special files are discussed in more detail in @ref{Pipes
391 and FIFOs}.
392 @end deftypevr
393 @cindex pipe signal
394 @cindex broken pipe signal
395
396 @comment signal.h
397 @comment POSIX.1
398 @deftypevr Macro int SIGUSR1
399 @end deftypevr
400 @comment signal.h
401 @comment POSIX.1
402 @deftypevr Macro int SIGUSR2
403 The @code{SIGUSR1} and @code{SIGUSR2} signals are set aside for you to
404 use any way you want.  They're useful for interprocess communication.
405 Since these signals are normally fatal, you should write a signal handler
406 for them in the program that receives the signal.
407
408 There is an example showing the use of @code{SIGUSR1} and @code{SIGUSR2}
409 in @ref{Signaling Another Process}.
410 @end deftypevr
411 @cindex user signals
412
413
414 @node Job Control Signals
415 @subsection Job Control Signals
416 @cindex job control signals
417
418 These signals are used to support job control.  If your system
419 doesn't support job control, then these macros are defined but the
420 signals themselves can't be raised or caught.
421
422 You should generally leave these signals alone unless you really
423 understand how job control works.  @xref{Job Control}.
424
425 @comment signal.h
426 @comment POSIX.1
427 @deftypevr Macro int SIGCHLD
428 This signal is sent to a parent process whenever one of its child
429 processes terminates or stops.
430
431 The default behavior for this signal is for it to be ignored.  If
432 you establish a handler for this signal while there are child processes
433 that have terminated but not reported their status via @code{wait} or
434 @code{waitpid} (@pxref{Process Completion}), whether
435 your new handler applies to those processes or not depends on the
436 particular operating system.
437 @end deftypevr
438 @cindex child process signal
439
440 @comment signal.h
441 @comment POSIX.1
442 @deftypevr Macro int SIGCONT
443 You can send a @code{SIGCONT} signal to a process to make it continue.
444 The default behavior for this signal is to make the process continue if
445 it is stopped, and for it to be ignored otherwise.
446 @end deftypevr
447 @cindex continue signal
448
449 @comment signal.h
450 @comment POSIX.1
451 @deftypevr Macro int SIGSTOP
452 The @code{SIGSTOP} signal stops the process.  It cannot be caught or
453 ignored.
454 @end deftypevr
455 @cindex stop signal
456
457 @comment signal.h
458 @comment POSIX.1
459 @deftypevr Macro int SIGTSTP
460 The @code{SIGTSTP} signal is an interactive stop signal.  Unlike
461 @code{SIGSTOP}, this signal can be caught or ignored.  Typically, you
462 trap this signal only if you have a special need to leave files or
463 system tables in a secure state when a process is stopped.
464
465 This signal is generated when the user types the SUSP character
466 (normally @kbd{C-z}).  For more information about terminal driver
467 support, @pxref{Special Characters}.
468 @end deftypevr
469 @cindex interactive stop signal
470
471 @comment signal.h
472 @comment POSIX.1
473 @deftypevr Macro int SIGTTIN
474 A process cannot read from the the user's terminal while it is running 
475 as a background job.  When any process in a background job tries to
476 read from the terminal, all of the processes in the job are sent a
477 @code{SIGTTIN} signal.  The default action for this signal is to
478 stop the process.  For more information about how this interacts with
479 the terminal driver, @pxref{Access to the Controlling Terminal}.
480 @end deftypevr
481 @cindex terminal input signal
482
483 @comment signal.h
484 @comment POSIX.1
485 @deftypevr Macro int SIGTTOU
486 This is similar to @code{SIGTTIN}, but is used when a process in a
487 background job attempts to write to the terminal.  Again, the default
488 action is to stop the process.
489 @end deftypevr
490 @cindex terminal output signal
491
492 While a process is stopped, no more signals can be delivered to it until
493 it is continued, except @code{SIGKILL} signals and (obviously)
494 @code{SIGCONT} signals.  The @code{SIGKILL} signal always causes
495 termination of the process and can't be blocked or ignored.  You can
496 block or ignore @code{SIGCONT}, but it always causes the process to
497 be continued anyway if it is stopped.  Sending a @code{SIGCONT} signal
498 to a process causes any pending stop signals for that process to be
499 discarded.  Likewise, any pending @code{SIGCONT} signals for a process
500 are discarded when it receives a stop signal.
501
502 The default action for a process that is a member of an orphaned
503 process group (@pxref{Process Termination Details}) that receives a
504 @code{SIGTSTP}, @code{SIGTTIN}, or @code{SIGTTOU} signal is not to stop
505 the process.  This makes sense; if a process is stopped by one of these
506 signals, it must be continued by the shell, and if a process group has
507 been orphaned, that means there's no shell around to continue the
508 processes.  Instead, the signal might be ignored, or the operating
509 system might turn the stop signal into another signal like @code{SIGHUP}.
510
511 @strong{Incomplete:}  What does the GNU system do?
512
513
514 @node Other Signals
515 @subsection Other Signals
516
517 @comment RMS flamed about this section, saying that ANSI signals should not
518 @comment be differentiated from non-ANSI signals.  But the purpose of
519 @comment this section is not to list non-ANSI signals (many of which are
520 @comment already listed in the appropriate sections above).  The purpose
521 @comment of this section is to warn users that there may be other signals 
522 @comment that are not supported on all hardware types.  According to mib
523 @comment and roland, the GNU system will not support all of the signals 
524 @comment listed in the BSD header files, for example.
525
526 Individual operating systems might support additional signals.  The ANSI
527 C standard reserves all identifiers beginning with @samp{SIG} followed
528 by an uppercase letter for the names of signals.  You should consult the
529 documentation or header files for your particular operating system and
530 processor type to find out about the specific signals it supports.
531
532 For example, some implementations support extra signals which correspond
533 to hardware traps.  Some other kinds of signals commonly supported are
534 used to implement limits on CPU time or file system usage, asynchronous
535 changes to terminal configuration, and the like.  And, an implementation
536 might define some signal names that are just synonyms for other signals.
537
538 You can generally assume that the default action (or the action set up
539 by the shell) for implementation-defined signals is reasonable, and not
540 worry about them yourself.  In fact, it's really a bad idea to ignore or
541 block signals you don't know anything about, or try to establish some
542 catch-all handler to take care of all random signals delivered to your
543 program.
544
545 @strong{Incomplete:}  The other signals listed are:
546
547 @table @code
548 @item SIGCLD
549 Obsolete name for @code{SIGCHLD}.
550
551 @item SIGTRAP
552 Generated by the machine's breakpoint instruction.  Used by debuggers.
553 Default action is to dump core.
554
555 @item SIGIOT
556 Generated by the PDP-11 ``iot'' instruction; equivalent to @code{SIGABRT}.
557 Default action is to dump core.
558
559 @item SIGEMT
560 Emulator trap, such as when you execute an unsupported instruction.
561 Default action is to dump core.
562
563 @item SIGSYS
564 Bad system call.
565 Default action is to dump core.
566
567 @item SIGPOLL
568 This is a System V thing, more or less equivalent to @code{SIGIO}.
569
570 @item SIGXCPU
571 CPU time limit exceeded.
572 Default action is program termination.
573
574 @item SIGXFSZ
575 File size limit exceeded.
576 Default action is program termination.
577
578 @item SIGWINCH
579 Window size change.  Sent by the system in response to @code{TIOCSWINSZ}
580 ioctl.
581 Default action is to ignore it.
582 @end table
583
584
585 @node Signal Messages
586 @subsection Signal Messages
587 @cindex signal messages
588
589 You can use the @code{strsignal} and @code{psignal} functions to get or
590 print a message string describing a signal.  The prototype for
591 @code{strsignal} is in @file{string.h}, and that for @code{psignal} in
592 @file{stdio.h}.
593 @pindex stdio.h
594 @pindex string.h
595
596 @comment string.h
597 @comment GNU
598 @deftypefun {char *} strsignal (int @var{signum})
599 This function returns a pointer to a statically-allocated string
600 containing a message describing the signal @var{signum}.  You
601 should not modify the contents of this string; and, since it can be
602 rewritten on subsequent calls, you should save a copy of it if you need
603 to reference it later.
604 @end deftypefun
605
606 @comment stdio.h
607 @comment GNU
608 @deftypefun void psignal (int @var{signum}, const char *@var{message})
609 This function prints a message describing the signal @var{signum}
610 to the stream @code{stderr}; @pxref{Standard Streams}.
611
612 If you call @code{psignal} with a @var{message} that is either a null
613 pointer or an empty string, @code{psignal} just prints the message 
614 corresponding to @var{signum}, adding a trailing newline.
615
616 If you supply a non-null @var{message} argument, then @code{psignal}
617 prefixes its output with this string.  It adds a colon and a space 
618 character to separate the @var{message} from the string corresponding
619 to @var{signum}.
620 @end deftypefun
621
622
623 @node Specifying Signal Actions
624 @section Specifying Signal Actions
625 @cindex signal actions
626
627 The simplest way to change the default action for a signal is to use the
628 @code{signal} function.  The GNU library also implements the more
629 complicated @code{sigaction} facility.  This section describes both
630 facilities and gives suggestions on which to use when.
631
632 @strong{Incomplete:}  RMS suggests putting an example here.
633
634 @menu
635 * Basic Signal Handling::       The simple @code{signal} function.
636 * Advanced Signal Handling::    The more powerful @code{sigaction} function.
637 * Sigaction Function Example::  An example of using the sigaction function.
638 * Sigaction Flags::             Specifying options for signal handling.
639 * Initial Signal Actions::      How programs inherit signal actions.
640 @end menu
641
642 @node Basic Signal Handling
643 @subsection Basic Signal Handling
644 @cindex @code{signal} function
645
646 The @code{signal} function provides a simple interface for establishing
647 an action for a particular signal.  The function and associated macros
648 are declared in the header file @file{signal.h}.
649 @pindex signal.h
650
651 @comment signal.h
652 @comment GNU
653 @deftp {Data Type} __sighandler_t
654 This is the type of signal handler functions.  Signal handlers take one
655 integer argument specifying the signal number, and have return type
656 @code{void}.  So, you should define handler functions like this:
657
658 @example
659 void @var{handler} (int @var{signum}) @{ @dots{} @}
660 @end example
661 @end deftp
662
663 @comment signal.h
664 @comment ANSI
665 @deftypefun __sighandler_t signal (int @var{signum}, __sighandler_t @var{action})
666 The @code{signal} function establishes @var{action} as the action for
667 the signal @var{signum}.
668
669 The first argument, @var{signum}, identifies the signal whose behavior you
670 want to control, and should be one of the signal names listed in
671 @ref{Signal Names}.  
672
673 The second argument, @var{action}, is a pointer to the function you want
674 to install as its handler.  This can be one of the following:
675
676 @itemize @bullet
677 @item 
678 @code{SIG_DFL}, to specify the default action for the particular signal.
679 The default actions are as described in @ref{Signal Names}.
680 @cindex default action for a signal
681
682 @item
683 @code{SIG_IGN}, to specify that the signal should be ignored.
684
685 It's not really a good idea to ignore most signals.  For one thing, you
686 cannot ignore the @code{SIGKILL} or @code{SIGSTOP} signals at all.  You
687 can have your program ignore program error signals like @code{SIGSEGV},
688 but doing so won't fix the bug in your program.  And, it is
689 user-unfriendly to ignore interactive signals like @code{SIGINT},
690 @code{SIGQUIT}, and @code{SIGTSTP}.
691 @cindex ignore action for a signal
692
693 As an alternative to ignoring a signal completely, it might make more
694 sense to block it temporarily.  @xref{Blocking Signals}.
695
696 @item 
697 A pointer to a function you write yourself.  For more information about
698 defining signal handler functions, @pxref{Defining a Signal Handler}.
699 @end itemize
700
701 If you set the action for a signal to @code{SIG_IGN}, or if you set it
702 to @code{SIG_DFL} and the default action is to ignore that signal, then
703 any pending signals of that type are discarded (even if they are still
704 blocked).
705
706 The @code{signal} function returns the action that was previously in
707 effect for the specified @var{signum}.  You can save this value and
708 restore it later by calling @code{signal} again.
709
710 If @code{signal} can't honor the request, it returns @code{SIG_ERR}
711 instead.  The following @code{errno} error conditions are defined for
712 this function:
713
714 @table @code
715 @item EINVAL
716 You specified an invalid @var{signum}; or you tried to ignore or provide
717 a handler for @code{SIGKILL} or @code{SIGSTOP}.
718 @end table
719 @end deftypefun
720
721 Here's a simple example of using the @code{signal} function.  The
722 following code causes @code{SIGUSR1} signals to be ignored, so that the
723 program can complete some critical operation that shouldn't be
724 interrupted by receipt of a signal of this type.  The variable
725 @code{old_action} stores whatever handler was in effect at the time.  At
726 the end of the operation, the program restores this handler.
727
728 @example
729 #include <signal.h>
730
731 void (*old_action)(int sig);
732
733 old_action = signal (SIGUSR1, SIG_IGN);  /* @r{Ignore the signal.} */
734 /* critical operations here */
735 signal (SIGUSR1, old_action);            /* @r{Allow the signal again.} */
736 @end example
737
738 @comment  Yes, I KNOW that signals arriving during the critical operations
739 @comment  will be lost.  But, I want only a very short example here, and do
740 @comment  not want to detract from the main point -- which is to show how to 
741 @comment  use the return value from signal to save and restore a signal
742 @comment  action -- with a long digression about ignoring signals being a 
743 @comment  bad idea and suggesting that people block the signal instead.
744
745 @comment signal.h
746 @comment SVID
747 @deftypefun __sighandler_t ssignal (int @var{signum}, __sighandler_t @var{action})
748 The @code{ssignal} function does the same thing as @code{signal}; it is
749 provided only for compatibility with SVID.
750 @end deftypefun
751
752
753 @comment signal.h
754 @comment ANSI
755 @deftypevr Macro __sighandler_t SIG_DFL
756 This macro can be used as the @var{action} argument to the @code{signal}
757 function.  It tells the system to use the default handling for the
758 signal.
759 @end deftypevr
760
761 @comment signal.h
762 @comment ANSI
763 @deftypevr Macro __sighandler_t SIG_IGN
764 This macro can be used as the @var{action} argument to the @code{signal}
765 function.  It tells the system to ignore the signal.
766 @end deftypevr
767
768 @comment signal.h
769 @comment ANSI
770 @deftypevr Macro __sighandler_t SIG_ERR
771 The value of this macro is used as the return value from @code{signal}
772 to indicate an error.
773 @end deftypevr
774
775 @ignore
776 @comment RMS says that ``we don't do this''.
777 Implementations might define additional macros for built-in signal
778 actions that are suitable as a @var{action} argument to @code{signal},
779 besides @code{SIG_IGN} and @code{SIG_DFL}.  Identifiers whose names
780 begin with @samp{SIG_} followed by an uppercase letter are reserved for
781 this purpose.
782 @end ignore
783
784
785 @node Advanced Signal Handling
786 @subsection Advanced Signal Handling
787 @cindex @code{sigaction} function
788
789 The @code{sigaction} function has the same basic effect as
790 @code{signal}: to specify how a signal should be handled by the process.
791 However, @code{sigaction} offers more control, at the expense of more
792 complexity.  In particular, @code{sigaction} allows you to specify
793 additional flags to control when the signal is generated and how the
794 handler is invoked.
795
796 The @code{sigaction} function is declared in @file{signal.h}.
797 @pindex signal.h
798
799 @comment signal.h
800 @comment POSIX.1
801 @deftp {struct Type} sigaction
802 Structures of type @code{sigaction} are used to specify signal actions
803 for the @code{sigaction} function.  It contains at least the following
804 members:
805
806 @table @code
807 @item __sighandler_t sa_handler
808 This is used in the same way as the @var{action} argument to the
809 @code{signal} function.  The value can be @code{SIG_DFL},
810 @code{SIG_IGN}, or a function pointer.  @xref{Basic Signal Handling}.
811
812 @item sigset_t sa_mask
813 This specifies a set of signals to be blocked while the handler runs.
814 Blocking is explained in @ref{Blocking Signals in a Handler}.
815
816 @item int sa_flags
817 This specifies various flags which can affect the behavior of 
818 the signal.  These are described in more detail in @ref{Sigaction Flags}.
819 @end table
820 @end deftp
821
822 @comment signal.h
823 @comment POSIX.1
824 @deftypefun int sigaction (int @var{signum}, const struct sigaction *@var{action}, struct sigaction *@var{old_action})
825 The @var{action} argument is used to set up a new action for the signal
826 @var{signum}, while the @var{old_action} argument is used to return
827 information about the action previously associated with this symbol.
828 (In other words, @var{old_action} has the same purpose as the
829 @code{signal} function's return value --- you can check to see what the
830 old action in effect for the signal was, and restore it later if you
831 want.)
832
833 Either @var{action} or @var{old_action} can be a null pointer.  If
834 @var{old_action} is a null pointer, this simply suppresses the return
835 of information about the old action.  If @var{action} is a null pointer,
836 the action associated with the signal @var{signum} is unchanged; this
837 allows you to inquire about how a signal is being handled without changing
838 that handling.
839
840 The return value from @code{sigaction} is zero if it succeeds, and
841 @code{-1} on failure.  The following @code{errno} error conditions are
842 defined for this function:
843
844 @table @code
845 @item EINVAL
846 The @var{signum} argument is not valid, or you are trying to
847 trap or ignore @code{SIGKILL} or @code{SIGSTOP}.
848 @end table
849 @end deftypefun
850
851 It's possible to use both the @code{signal} and @code{sigaction}
852 functions within a single program, but you have to be careful because
853 they can interact in slightly strange ways.
854
855 In particular, since the @code{sigaction} function specifies more
856 information than the @code{signal} function, the return value from
857 @code{signal} might not be usable to restore an action originally
858 established by @code{sigaction}.
859
860 You can rely on the old action structure returned by @code{sigaction}
861 being restorable by another call to @code{sigaction}, even if the action
862 was originally established by @code{signal}.  However, the function
863 returned as the @code{sa_handler} member of this structure might not be
864 the same as the @var{action} function specified as an argument to
865 @code{signal}, and might not be usable by itself as an argument to
866 @code{signal}.
867
868 So, you're better off using one or the other of the mechanisms
869 consistently within a single program.  
870
871 @strong{Portability Note:} The basic @code{signal} function is a feature
872 of ANSI C, while @code{sigaction} is part of the POSIX.1 standard.  If
873 you are concerned about portability to non-POSIX systems, then you
874 should use the @code{signal} function instead.
875
876 @node Sigaction Function Example
877 @subsection Sigaction Function Example
878
879 In @ref{Basic Signal Handling}, this short example was used to illustrate
880 the use of the @code{signal} function to cause @code{SIGUSR1} signals
881 to be ignored temporarily:
882
883 @example
884 #include <signal.h>
885
886 void (*old_action)(int sig);
887
888 old_action = signal (SIGUSR1, SIG_IGN);  /* @r{Ignore the signal.} */
889 /* critical operations here */
890 signal (SIGUSR1, old_action);            /* @r{Allow the signal again.} */
891 @end example
892
893 Now let's see how the same thing is done with the @code{sigaction}
894 function:
895
896 @example
897 struct sigaction new_action, old_action;
898 sigset_t block_mask;
899
900 /* @r{Set up the structure to specify the new action.} */
901 sigfillset (&block_mask);
902
903 new_action.sa_handler = SIG_IGN;
904 new_action.sa_mask = block_mask;
905 new_action.sa_flags = 0;
906
907 sigaction (SIGUSR1, &new_action, &old_action);
908 /* @r{Critical actions here.} */
909 sigaction (SIGUSR1, &old_action, NULL);
910 @end example
911
912 The activities on @code{block_mask} are described later; @pxref{Blocking
913 Signals}.  The program just loads the @code{new_action} structure with
914 the desired parameters and passes it in the @code{sigaction} call.
915
916 In the first call to @code{sigaction}, we want to save the existing
917 action for the signal, so it can be restored later.  So a pointer to the
918 @code{old_action} structure is passed as the third argument.  On the
919 second call, we don't need any information returned about the existing
920 action, so a null pointer is passed instead.
921
922 Here is another example.  It retrieves information about the current
923 action for @code{SIGINT} without changing that action.
924
925 @example
926 struct sigaction query_action;
927
928 if (sigaction (SIGINT, NULL, &query_action) < 0)
929   /* @r{@code{sigaction} returns -1 in case of error} */ 
930 else if (query_action.sa_handler == SIG_DFL)
931   /* @r{@code{SIGINT} is handled in the default, fatal manner} */
932 else if (query_action.sa_handler == SIG_IGN)
933   /* @r{@code{SIGINT} is ignored} */
934 else
935   /* @r{A programmer-defined signal handler is in effect} */
936 @end example
937
938
939 @node Sigaction Flags
940 @subsection Sigaction Flags
941 @cindex @code{sigaction} flags
942
943 This @code{sa_flags} member of the @code{sigaction} structure is a
944 catch-all for special features.  Most of the time, you can simply use
945 @code{0} for this field.
946
947 The value of @code{sa_flags} is interpreted as a bit mask.  Thus, you
948 can choose the flags you want to have set for some reason, OR those
949 flags together, and assign them to the @code{sa_flags} member of your
950 @code{sigaction} structure.
951
952 These macros are defined in the header file @file{signal.h}.
953 @pindex signal.h
954
955 @comment signal.h
956 @comment POSIX.1
957 @deftypevr Macro int SA_NOCLDSTOP
958 The value of this macro is an integer constant that can be used as a
959 flag for @code{sa_flags} when setting up an action for the
960 @code{SIGCHLD} signal.  When the flag is set, the system delivers the
961 signal for a terminated child process but not for one that is stopped.
962 By default, @code{SIGCHLD} is delivered for both terminated children and
963 stopped children.
964 @end deftypevr
965
966 @comment signal.h
967 @comment BSD
968 @deftypevr Macro int SA_ONSTACK
969 If this flag is set, the system uses the signal stack when delivering
970 the signal.  @xref{BSD Signal Handling}.
971 @end deftypevr
972
973 @comment signal.h
974 @comment BSD
975 @deftypevr Macro int SA_RESTART
976 If this flag is set, system calls interrupted by a signal return with
977 an @code{EINTR} error instead of restarting.
978 @end deftypevr
979
980
981
982 @node Initial Signal Actions
983 @subsection Initial Signal Actions
984 @cindex initial signal actions
985
986 When a new process is created (@pxref{Creating a Process}), it inherits
987 handling of signals from its parent process.  However, when you load a
988 new process image using the @code{exec} function (@pxref{Executing a
989 File}), any signals that you've defined your own handlers for revert to
990 their @code{SIG_DFL} handling.  (If you think about it a little, this
991 makes sense; the handler functions from the old program are specific to
992 that program, and aren't even present in the address space of the new
993 program image.)  Of course, the new program can establish its own
994 handlers.
995
996 When a program is run by a shell, the shell normally sets the initial
997 actions for the child process to @code{SIG_DFL} or @code{SIG_IGN}, as
998 appropriate.  It's a good idea to check to make sure that the shell has
999 not set up an initial action of @code{SIG_IGN} before you establish your
1000 own signal handlers.
1001
1002 @strong{Incomplete:}  RMS suggests putting an example here.
1003
1004
1005 @node Defining a Signal Handler
1006 @section Defining a Signal Handler
1007
1008 This section describes how to write a signal handler function that can
1009 be established with the @code{signal} or @code{sigaction} functions.
1010
1011 A signal handler is just a function that you compile together with the
1012 rest of the program.  Instead of directly invoking the function, you use
1013 @code{signal} or @code{sigaction} to tell the operating system to call
1014 it when a signal arrives.  This is known as @dfn{enabling} the handler.
1015 @cindex enabling a signal handler
1016 @cindex signal handler function
1017
1018 You need to take special care in writing handler functions because they
1019 can be called asynchronously.  That is, a handler might be called at any
1020 point in the program, unpredictably.  If two signals arrive during a
1021 very short interval, the operating system might even restart the handler
1022 while it is handling the first signal!  This section describes what your
1023 handler should do, and what you should avoid.
1024
1025 @menu
1026 * Signal Handler Example::              An example.
1027 * Handling Multiple Signals::           What happens if another signal arrives
1028                                          when your handler function is running.
1029 * Restrictions on Handler Functions::   What handlers can and can't do.
1030 @end menu
1031
1032 @node Signal Handler Example
1033 @subsection Signal Handler Example
1034
1035 There are two basic strategies you can use in signal handler functions:
1036
1037 @itemize @bullet
1038 @item
1039 You can have the handler function note that the signal arrived by
1040 tweaking some global data structures, and then return normally.
1041
1042 @item
1043 You can have the handler function terminate the program or transfer
1044 control to a point where it can recover from the situation that caused
1045 the signal.
1046 @end itemize
1047
1048 Handlers which return normally are usually only useful for signals such
1049 as @code{SIGALRM} and other interprocess communication signals.  This
1050 isn't a reliable technique for handling program error signals like
1051 @code{SIGFPE} and @code{SIGSEGV}, because the behavior of the program
1052 when the handler function returns is not defined after a program error.
1053
1054 Typically, a handler that returns normally tweaks some global data
1055 structures that are examined synchronously from time to time during
1056 normal execution of the program.
1057
1058 Here is a simple example of such a program.  It executes the body of
1059 the loop until it has noticed that a @code{SIGALRM} signal has arrived.
1060 This technique is useful because it allows the iteration in progress
1061 when the signal arrives to complete before the loop exits.
1062
1063 @example
1064 #include <signal.h>
1065 #include <stdlib.h>
1066
1067 /* @r{This flag controls termination of the main loop.} */
1068
1069 volatile sig_atomic_t keep_going = 1;
1070
1071
1072 /* @r{The signal handler just clears the flag and re-enables itself.}
1073  * @r{Actually, for this program re-enabling the handler isn't necessary,}
1074  * @r{since only one alarm signal has to be caught in order to cause it}
1075  * @r{to terminate.}
1076  */
1077
1078 void catch_alarm (int sig)
1079 @{
1080   keep_going = 0;
1081   signal (sig, catch_alarm);
1082 @}
1083
1084 main (void)
1085 @{
1086   
1087   /* @r{Establish a handler for @code{SIGALRM} signals.} */
1088   signal (SIGALRM, catch_alarm);
1089
1090   /* @r{Set an alarm to go off in a little while.}  */
1091   alarm (2);
1092
1093   /* @r{Check the flag once in a while to see when to quit.} */
1094   while (keep_going)
1095     do_stuff ();
1096   exit (EXIT_SUCCESS);
1097 @}      
1098 @end example
1099
1100 Handler functions that cause a nonlocal transfer of control or program
1101 termination are typically used to cause orderly cleanup or recovery from
1102 program error signals and interactive interrupts.
1103
1104 Process termination within a handler is typically performed by resending
1105 the signal.  For example, GNU Emacs sets up a handler for most fatal
1106 signals that looks something like:
1107
1108 @example
1109 volatile sig_atomic_t fatal_error_in_progress = 0;
1110
1111 void fatal_error_signal (int sig)
1112 @{
1113
1114   /* @r{Immediately set the action for this signal back to the default.}
1115    * @r{This will prevent the handler from being invoked recursively if}
1116    * @r{another fatal signal happens while the handler is executing.}
1117    */
1118   signal (sig, SIG_DFL);
1119
1120   /* @r{Since this handler is established for more than one kind of signal, }
1121    * @r{it might still get invoked recursively by delivery of some other kind}
1122    * @r{of signal.  Use a static variable to keep track of that.}
1123    */
1124
1125   if (fatal_error_in_progress)
1126     raise (sig);
1127   fatal_error_in_progress = 1;
1128
1129   /* @r{Now do the clean up actions:}
1130    * @r{- reset terminal modes}
1131    * @r{- kill child processes}
1132    * @r{- auto save buffers being edited}
1133    * @r{- remove lock files}
1134    */
1135   @dots{}
1136
1137   /* @r{Now resend the signal.  Since we set the handling for it back to}
1138    * @r{its default, this will cause the program to terminate.  We could}
1139    * @r{just call @code{exit} or @code{abort} here, but resending the signal}
1140    * @r{will set the return status from the process correctly.}
1141    */
1142   raise (sig);
1143 @}
1144 @end example
1145
1146 You can do a nonlocal transfer of control out of a signal handler using
1147 the @code{setjmp} and @code{longjmp} facilities (@pxref{Non-Local
1148 Exits}).  However, if you do this, you must take care in setting up the
1149 return point.  For example, if you want to make sure that global data
1150 structures are in a consistent state after doing a @code{longjmp} out of
1151 a signal handler, you must either re-initialize them or else ensure that
1152 your signal handler won't be invoked while they are in an inconsistent
1153 state by blocking signals around the critical sections of your program.
1154 @xref{Blocking Signals}.
1155 @cindex non-local exit, from signal handler
1156
1157 @strong{Incomplete:}  RMS suggests putting another example here.
1158
1159
1160 @node Handling Multiple Signals
1161 @subsection Handling Multiple Signals
1162 @cindex race conditions, relating to signals
1163 @cindex handling multiple signals
1164
1165 What happens if another signal arrives when your signal handler function
1166 is running?
1167
1168 In the GNU system, when a handler for a particular signal is invoked,
1169 that signal is normally blocked until the handler returns.  That means
1170 that if two signals of the same kind arrive close together, the second
1171 one will be held until the first has been handled.  (The handler can
1172 explicitly unblock the signal using @code{sigprocmask}, if you want to
1173 allow more signals of this type to arrive; @pxref{Process Signal Mask})
1174
1175 However, your handler can still be interrupted by delivery of another
1176 kind of signal.  To avoid this, you can use the @code{sa_mask} member of
1177 the action structure passed to @code{sigaction} to explicitly specify
1178 which signals should be blocked while the signal handler runs.  These
1179 signals are in addition to the signal for which the handler was invoked,
1180 and any other signals that are normally blocked by the process.
1181 @xref{Blocking Signals in a Handler}.
1182
1183 If more than one signal of the same type is delivered to your process
1184 before your signal handler has a chance to be invoked at all, your
1185 handler may only be invoked once, as if only a single signal had
1186 arrived.  This situation can arise when the signal is blocked, or in a
1187 multiprocessing environment where the system is busy running some other
1188 processes while the signals are delivered.  This means, for example,
1189 that you cannot reliably use a signal handler to count signals.
1190
1191 @strong{Incomplete:} RMS suggests putting an example here showing a
1192 handler for @code{SIGCHLD}; the handler needs to have a loop since there
1193 may be more than one child process with status information available.
1194
1195 @strong{Portability Note:} In System V Unix, handlers established with
1196 @code{signal} behave somewhat differently.  Before calling the handler
1197 function, the action for the signal is set back to @code{SIG_DFL}.  This
1198 means that the handler must re-enable itself before exiting and do any
1199 signal blocking explicitly.  It also means that there is still a
1200 possibility that another signal could arrive in the moment before you've
1201 had a chance to alter the handling of the signal.  The ANSI C standard
1202 permits this behavior, but you do not need to worry about this if you
1203 are using only the GNU system.
1204
1205
1206 @node Restrictions on Handler Functions
1207 @subsection Restrictions on Handler Functions
1208 @cindex restrictions on signal handler functions
1209
1210 Handler functions usually don't do very much.  The recommended behavior
1211 is to just have the handler set an external variable that the program
1212 checks regularly, and leave all serious work to the program.  This is
1213 because the handler can be called at asynchronously, at unpredictable
1214 times --- perhaps in the middle of a system call, or even between the
1215 beginning and the end of a floating-point operation that requires
1216 multiple instructions.  The data structures being manipulated might
1217 therefore be in an inconsistent state when the handler function is
1218 invoked.
1219
1220 This means you have to be very careful about what you do in a signal
1221 handler.
1222
1223 @itemize @bullet
1224 @item
1225 Do not call any functions, including those from the standard libraries,
1226 unless you are sure they are @dfn{reentrant} with respect to signals.
1227 @cindex reentrant functions
1228
1229 The most usual reason why a function fails to be reentrant is the use of
1230 static or global data structures.  As an example of what can go wrong,
1231 suppose that the sample program prints a message through a @code{printf}
1232 call in the signal handler.  Suppose also that @code{printf} and
1233 @code{fprintf} share some common internal data structures, and that the
1234 main program was in the middle of an @code{fprintf} call when the signal
1235 was delivered.  Both the signal handler's message and the program's data
1236 could end up getting corrupted.
1237
1238 @strong{Incomplete:} There should be a table here listing functions that
1239 are guaranteed to be reentrant, and/or something in each individual
1240 function description to indicate whether it's reentrant.
1241
1242 @item
1243 If your handler calls any library functions that can modify the value of
1244 @code{errno}, it should save and restore the original value of
1245 @code{errno} before returning normally.  This prevents errors that occur
1246 within the signal handler from being confused with errors from system
1247 calls at the point the program is interrupted to run the handler.
1248
1249 @item
1250 If your handler needs to access any global variables from your program,
1251 those variables must be declared @code{volatile}.  This tells the
1252 compiler that the value of the variable might change asynchronously, and
1253 keeps it from making some kinds of optimizations that would be
1254 invalidated by such modifications.
1255 @cindex @code{volatile} declarations
1256
1257 @item
1258 The only data type that can be accessed as an atomic operation is the
1259 @code{sig_atomic_t} type.  Accesses to other kinds of objects might be
1260 interruptible by a signal; the data might be in an inconsistent state
1261 when the handler function is called.  There are similar problems if your
1262 handler uses a set of variables which are supposed to be updated
1263 together.
1264
1265 The way you can get around this problem is by blocking all signals that
1266 have handlers that might access the variables around all the parts of
1267 the program that manipulate the variables, including in the handlers
1268 themselves.  @xref{Blocking Signals}, for information on how to do this.
1269 @end itemize
1270
1271 @comment signal.h
1272 @comment ANSI
1273 @deftp {Data Type} sig_atomic_t
1274 This is an integer data type.  It identifies a type of object that can
1275 be accessed as an atomic entity, even in the presence of asynchronous
1276 interrupts.
1277 @end deftp
1278
1279 @strong{Incomplete:} RMS suggests putting an example here to show what
1280 this implies.
1281
1282
1283 @node Generating Signals
1284 @section Generating Signals
1285 @cindex sending signals
1286 @cindex raising signals
1287 @cindex signals, generating
1288
1289 Besides signals that are generated as a result of a hardware trap or
1290 interrupt, your program can explicitly send signals to itself or to
1291 another process.
1292
1293 @menu
1294 * Raising a Signal::            Send yourself any desired signal.
1295 * Signaling Another Process::   Send a signal to another process.
1296 @end menu
1297
1298
1299 @node Raising a Signal
1300 @subsection Raising a Signal
1301
1302 A process can send itself a signal with the @code{raise} function.  This
1303 function is declared in @file{signal.h}.
1304 @pindex signal.h
1305
1306 @comment signal.h
1307 @comment ANSI
1308 @deftypefun int raise (int @var{signum})
1309 The @code{raise} function sends the signal @var{signum} to the calling
1310 process.  It returns zero if successful and a nonzero value if it fails.
1311 About the only reason for failure would be if the value of @var{signum}
1312 is invalid.
1313 @end deftypefun
1314
1315 @comment signal.h
1316 @comment SVID
1317 @deftypefun int gsignal (int @var{signum})
1318 The @code{gsignal} function does the same thing as @code{raise}; it is
1319 provided only for compatibility with SVID.
1320 @end deftypefun
1321
1322 One convenient use for @code{raise} is to reproduce the default behavior
1323 of a signal that you have trapped.  For instance, suppose a user of your
1324 program types the SUSP character (usually @kbd{C-z}; @pxref{Special
1325 Characters}) to send it an interactive stop stop signal
1326 (@code{SIGTSTP}), and you want to clean up some internal data buffers
1327 before stopping.  You might set this up like this:
1328
1329 @comment RMS suggested getting rid of the handler for SIGCONT in this function.
1330 @comment But that would require that the handler for SIGTSTP unblock the
1331 @comment signal before doing the call to raise.  We haven't covered that
1332 @comment topic yet, and I don't want to distract from the main point of
1333 @comment the example with a digression to explain what is going on.  As
1334 @comment the example is written, the signal that is raise'd will be delivered
1335 @comment as soon as the SIGTSTP handler returns, which is fine.
1336
1337 @example
1338 #include <signal.h>
1339
1340 /* @r{When a stop signal arrives, set the action back to the default}
1341  * @r{and then resend the signal after doing cleanup actions.}
1342  */
1343
1344 void tstp_handler (int sig)
1345 @{
1346   signal (SIGTSTP, SIG_DFL);
1347   /* @r{Do cleanup actions here.} */
1348   @dots{}
1349   raise (SIGTSTP);
1350 @}
1351
1352 /* @r{When the process is continued again, restore the signal handler.}
1353  */
1354
1355 void cont_handler (int sig)
1356 @{
1357   signal (SIGCONT, cont_handler);
1358   signal (SIGTSTP, tstp_handler);
1359 @}
1360
1361 /* @r{Enable both handlers during program initialization.}
1362  */
1363
1364 main (void)
1365 @{
1366   signal (SIGCONT, cont_handler);
1367   signal (SIGTSTP, tstp_handler);
1368   @dots{}
1369 @}
1370 @end example
1371
1372
1373 @node Signaling Another Process
1374 @subsection Signaling Another Process
1375
1376 @cindex killing a process
1377 The @code{kill} function can be used to send a signal to another process.
1378 In spite of its name, it can be used for a lot of things other than
1379 causing a process to terminate.  Some examples of situations where you
1380 might want to send signals between processes are:
1381
1382 @itemize @bullet
1383 @item
1384 A parent process starts a child to perform a task --- perhaps having the
1385 child running an infinite loop --- and then terminates the child when
1386 the task is no longer needed.
1387
1388 @item
1389 A process executes as part of a group, and needs to terminate or notify
1390 the other processes in the group when an error or other event occurs.
1391
1392 @item
1393 Two processes need to synchronize while working together.
1394 @end itemize
1395
1396 This section assumes that you know a little bit about how processes
1397 work.  For more information on this subject, @pxref{Processes}.
1398
1399 The @code{kill} function is declared in @file{signal.h}.
1400 @pindex signal.h
1401
1402 @comment signal.h
1403 @comment POSIX.1
1404 @deftypefun int kill (pid_t @var{pid}, int @var{signum})
1405 The @code{kill} function sends the signal @var{signum} to the process
1406 or process group specified by @var{pid}.  Besides the signals listed in
1407 @ref{Signal Names}, @var{signum} can also have a value of zero to
1408 check the validity of the @var{pid}.
1409
1410 The @var{pid} specifies the process or process group to receive the
1411 signal:
1412
1413 @table @code
1414 @item @var{pid} > 0
1415 The process whose identifier is @var{pid}.
1416
1417 @item @var{pid} == 0
1418 All processes in the same process group as the sender.  The sender
1419 itself does not receive the signal.
1420
1421 @item @var{pid} < -1
1422 The process group whose identifier is the absolute value of
1423 @var{pid}.
1424
1425 @item @var{pid} == -1
1426 If the process is privileged, send the signal to all processes except
1427 for some special system processes.  Otherwise, send the signal to all
1428 processes with the same effective user ID.
1429 @end table
1430
1431 If @code{kill} is used by a process to send a signal to itself, and the
1432 signal is not blocked, then @code{kill} delivers at least one signal
1433 (which might be some other pending unblocked signal instead of the
1434 signal @var{signum}) to that process before it returns.
1435
1436 The return value from @code{kill} is zero if the signal can be sent
1437 successfully.  Otherwise, no signal is sent, and a value of @code{-1} is
1438 returned.
1439
1440 The following @code{errno} error conditions are defined for this function:
1441
1442 @table @code
1443 @item EINVAL
1444 The @var{signum} argument is an invalid or unsupported number.
1445
1446 @item EPERM
1447 You do not have the privilege to send a signal to the process or any of
1448 the processes in the process group named by @var{pid}.
1449
1450 @item ESCRH
1451 The @var{pid} argument does not refer to an existing process or group.
1452 @end table
1453 @end deftypefun
1454
1455 @comment signal.h
1456 @comment BSD
1457 @deftypefun int killpg (int @var{pgid}, int @var{signum})
1458 This is similar to @code{kill}, but sends signal @var{signum} to the
1459 process group @var{pgid}.  This function is provided for compatibility
1460 with BSD; using @code{kill} to do this is more portable.
1461 @end deftypefun
1462
1463 There are restrictions that prevent you from using @code{kill} to send
1464 signals to any random process.  In typical use, @code{kill} is used to
1465 pass signals between parent, child, and sibling processes, and in these
1466 situations you don't have to worry too much about getting the
1467 appropriate permissions to send signals.  The restrictions on who can
1468 send signals to process are intended to prevent antisocial behavior like
1469 arbitrarily killing off processes belonging to another user.
1470
1471 Whether a process has permission to send a signal to another process
1472 is determined by the user IDs of the two processes.  This concept is
1473 discussed in detail in @ref{User/Group IDs of a Process}.
1474
1475 Generally, for a process to be able to send a signal to another process,
1476 either the sending process must belong to a privileged user (like
1477 @samp{root}), or the real or effective user ID of the sending process
1478 must match the real or effective user ID of the receiving process.  If
1479 the receiving process has changed its effective user ID from the
1480 set-user-ID mode bit on its process image file, then the owner of the
1481 process image file is used in place of its current effective user ID.
1482 In some implementations, a parent process might be able to send signals
1483 to a child process even if the user ID's don't match, and other
1484 implementations might enforce other restrictions.
1485
1486 The @code{SIGCONT} signal is a special case.  It can be sent if the
1487 sender is part of the same session as the receiver, regardless of
1488 user IDs.
1489
1490 As a simple example of @code{kill}, the call:
1491
1492 @example
1493 kill (getpid (), @var{sig})
1494 @end example
1495
1496 @noindent
1497 has the same effect as:
1498
1499 @example
1500 raise (@var{sig})
1501 @end example
1502
1503 @cindex interprocess communication, with signals
1504 Here is a longer example showing how signals can be used for
1505 interprocess communication.  This is what the @code{SIGUSR1} and
1506 @code{SIGUSR2} signals are provided for.  Since these signals are fatal
1507 by default, the process that is supposed to receive them must trap them
1508 through @code{signal} or @code{sigaction}.
1509
1510 In this example, a parent process forks a child process and then waits
1511 for the child to complete its initialization.  The child process tells
1512 the parent when it is ready by sending it a @code{SIGUSR1} signal, using
1513 the @code{kill} function.
1514
1515 @example
1516 #include <signal.h>
1517 #include <stdio.h>
1518 #include <sys/types.h>
1519 #include <unistd.h>
1520
1521 /* @r{When a @code{SIGUSR1} signal arrives, set this variable.}
1522  */
1523
1524 volatile sig_atomic_t usr_interrupt = 0;
1525
1526 void synch_signal (int sig)
1527 @{
1528   usr_interrupt = 1;
1529 @}
1530
1531
1532 /* @r{The child process executes this function.}
1533  */
1534
1535 void child_function (void)
1536 @{
1537   /* @r{Perform initialization.} */
1538   printf ("I'm here!!!  My pid is %d.\n", (int)getpid());
1539
1540   /* @r{Let parent know you're done.} */
1541   kill (getppid (), SIGUSR1);  
1542
1543   /* @r{Continue with execution.} */
1544   printf ("Bye, now....\n");
1545   exit (0);
1546 @}
1547
1548
1549 void main (void)
1550 @{
1551   struct sigaction usr_action;
1552   sigset_t block_mask;
1553   pid_t child_id;
1554
1555   /* @r{Establish the signal handler.} */
1556   sigfillset (&block_mask);
1557   usr_action.sa_handler = synch_signal;
1558   usr_action.sa_mask = block_mask;
1559   usr_action.sa_flags = 0;
1560   sigaction (SIGUSR1, &usr_action, NULL);
1561
1562   /* @r{Create the child process.} */
1563   if ((child_id = fork ()) == 0)
1564     child_function ();  /* @r{Does not return} */
1565
1566   /* @r{Busy wait for child to send a signal.} */
1567   while (!usr_interrupt) @{@}
1568
1569   /* @r{Now continue execution.} */
1570   printf ("That's all, folks!\n");
1571   exit (0);
1572 @}
1573 @end example
1574
1575 Using a busy wait, as this program does, is not really a good idea.
1576 There is an example in @ref{Waiting for a Signal} that shows you how
1577 you can make a program block until a signal arrives.
1578
1579 @node Blocking Signals
1580 @section Blocking Signals
1581 @cindex blocking signals
1582
1583 Blocking a signal means telling the operating system to hold it and
1584 deliver it later.  Generally, a program does not block signals
1585 indefinitely --- it might as well ignore them by setting their actions
1586 to @code{SIG_IGN}.  But it is useful to block signals briefly, to
1587 prevent them from interrupting sensitive operations.  For instance:
1588
1589 @itemize @bullet
1590 @item
1591 You can use the @code{sigprocmask} function to block signals while you
1592 modify global variables that are also modified by the handlers for these 
1593 signals.
1594
1595 @item
1596 You can set @code{sa_mask} in your @code{sigaction} call so that the
1597 signal handler can run without being interrupted itself by signals.
1598 @end itemize
1599
1600 @menu
1601 * Signal Sets::                         How to specify which signals to block.
1602 * Process Signal Mask::                 Blocking delivery of signals to your
1603                                          process during normal execution.
1604 * Blocking Signals in a Handler::       Blocking additional signals while a
1605                                          handler is being run.
1606 * Checking for Pending Signals::        How to tell if there are signals
1607                                          waiting to be delivered.
1608 @end menu
1609
1610 @node Signal Sets
1611 @subsection Signal Sets
1612
1613 All of the signal blocking functions use a data structure called a
1614 @dfn{signal set} to specify what signals are affected.  Thus, every
1615 activity involves two stages: creating the signal set, and then passing
1616 it as an argument to a library function.
1617 @cindex signal set
1618
1619 These facilities are declared in the header file @file{signal.h}.
1620 @pindex signal.h
1621
1622 @comment signal.h
1623 @comment POSIX.1
1624 @deftp {Data Type} sigset_t
1625 The @code{sigset_t} data type is used to represent a signal set.
1626 Internally, it may be implemented as either an integer or structure
1627 type.  A bitmask representation is typical, but you're better off using
1628 the various functions described in this section to initialize, change,
1629 and retrieve information from @code{sigset_t} objects, than trying to
1630 manipulate them directly.
1631 @end deftp
1632
1633 There are two ways to initialize a signal set.  You can initially
1634 specify it to be empty with @code{sigemptyset} and then add specified
1635 signals individually.  Or you can specify it to be full with
1636 @code{sigfillset} and then delete specified signals individually.  You
1637 must always initialize the signal set with one of these two functions
1638 before using it in any other way.  You can't just set all the signals
1639 explicitly because the @code{sigset_t} object might include some other
1640 information (like a version field) that needs to be initialized as well.
1641
1642 @comment signal.h
1643 @comment POSIX.1
1644 @deftypefun int sigemptyset (sigset_t *@var{set})
1645 This function is used to initialize the signal set @var{set} to 
1646 exclude all of the defined signals.  The return value is @code{0}.
1647 @end deftypefun
1648
1649 @comment signal.h
1650 @comment POSIX.1
1651 @deftypefun int sigfillset (sigset_t *@var{set})
1652 This function is used to initialize the signal set @var{set} to include
1653 all of the defined signals.  Again, the return value is @code{0}.
1654 @end deftypefun
1655
1656 @comment signal.h
1657 @comment POSIX.1
1658 @deftypefun int sigaddset (sigset_t *@var{set}, int @var{signum})
1659 This function adds the signal @var{signum} to the signal set @var{set}.
1660 All @code{sigaddset} does is modify @var{set}; it does not block or
1661 unblock any signals.
1662
1663 The return value is @code{0} on success and @code{-1} on failure.
1664 The following @code{errno} error condition is defined for this function:
1665
1666 @table @code
1667 @item EINVAL
1668 The @var{signum} argument doesn't specify a valid signal.
1669 @end table
1670 @end deftypefun
1671
1672 @comment signal.h
1673 @comment POSIX.1
1674 @deftypefun int sigdelset (sigset_t *@var{set}, int @var{signum})
1675 This function removes the signal @var{signum} from the signal set
1676 @var{set}.  All @code{sigdelset} does is modify @var{set}; it does not
1677 block or unblock any signals.  The return value and error conditions are
1678 the same as for @code{sigaddset}.
1679 @end deftypefun
1680
1681 Finally, there is this predicate function:
1682
1683 @comment signal.h
1684 @comment POSIX.1
1685 @deftypefun int sigismember (const sigset_t *@var{set}, int @var{signum})
1686 The @code{sigismember} function tests whether the signal @var{signum} is
1687 a member of the signal set @var{set}.  It returns @code{1} if the signal
1688 is in the set, @code{0} if not, and @code{-1} if there is an error.
1689
1690 The following @code{errno} error condition is defined for this function:
1691
1692 @table @code
1693 @item EINVAL
1694 The @var{signum} argument doesn't specify a valid signal.
1695 @end table
1696 @end deftypefun
1697
1698
1699 @node Process Signal Mask
1700 @subsection Process Signal Mask
1701
1702 The collection of signals that are currently blocked is called the
1703 @dfn{signal mask}.  Each process has its own signal mask.  When you
1704 create a new process (@pxref{Creating New Processes}), it inherits
1705 its parent's mask.
1706 @cindex signal mask
1707 @cindex process signal mask
1708
1709 The prototype for the @code{sigprocmask} function is in @file{signal.h}.
1710 @pindex signal.h
1711
1712 @comment signal.h
1713 @comment POSIX.1
1714 @deftypefun int sigprocmask (int @var{how}, const sigset_t *@var{set}, sigset_t *@var{oldset})
1715 The @code{sigprocmask} function is used to examine or change the calling
1716 process's signal mask.  The @var{how} argument determines how the signal
1717 mask is changed, and must be one of the following values:
1718
1719 @table @code
1720 @item SIG_BLOCK
1721 Add the signals in @var{set} to the existing mask.  In other words, the
1722 new mask is the union of the existing mask and @var{set}.
1723
1724 @item SIG_UNBLOCK
1725 Remove the signals in @var{set} from the existing mask.
1726
1727 @item SIG_SETMASK
1728 Use @var{set} for the mask; ignore current contents of the mask.
1729 @end table
1730
1731 The last argument, @var{oldset}, is used to return information about the
1732 old process signal mask.  If you just want to change the mask without
1733 looking at it, pass a null pointer as the @var{oldset} argument.
1734 Similarly, if you want to know what's in the mask without changing it,
1735 pass a null pointer for @var{set} (in this case the @var{how} argument
1736 is not significant).  The @var{oldset} argument is particularly useful
1737 if you want to remember the original set of blocked signals in order to
1738 restore it later.  (Since the signal mask is inherited over @code{fork}
1739 and @code{exec} calls, you can't predict what its contents are when your
1740 program starts running.)
1741
1742 If invoking @code{sigprocmask} causes any pending signals to be
1743 unblocked, at least one of those signals is delivered to the process
1744 before @code{sigprocmask} returns.  The order in which pending signals
1745 are delivered is not specified, but you can set up a hierarchy by making
1746 multiple @code{sigprockmask} calls to unblock various signals one at
1747 a time.
1748
1749 The @code{sigprocmask} function returns @code{0} if successful, and @code{-1}
1750 to indicate an error.  The following @code{errno} error conditions are
1751 defined for this function:
1752
1753 @table @code
1754 @item EINVAL
1755 The @var{how} argument is invalid.
1756 @end table
1757
1758 You can't block the @code{SIGKILL} and @code{SIGSTOP} signals, but
1759 if the signal set includes these, @code{sigprocmask} just ignores
1760 them instead of returning an error status.
1761
1762 Remember, too, that blocking program error signals such as @code{SIGFPE}
1763 usually doesn't do anything useful for signals generated by an actual
1764 program error (as opposed to signals sent with @code{raise} or
1765 @code{kill}).  This is because your program may be too broken to be
1766 able to continue executing to a point where the signal is unblocked
1767 again.
1768 @end deftypefun
1769
1770 @comment signal.h
1771 @comment POSIX.1
1772 @deftypevr Macro int SIG_BLOCK
1773 The value of this macro is an integer suitable for use as the @var{how}
1774 argument to @code{sigprocmask}, to specify that the process signal mask
1775 should be set to the union of the specified set with the current process
1776 signal mask.
1777 @end deftypevr
1778
1779 @comment signal.h
1780 @comment POSIX.1
1781 @deftypevr Macro int SIG_UNBLOCK
1782 The value of this macro is an integer suitable for use as the @var{how}
1783 argument to @code{sigprocmask}, to specify that the signals in the
1784 specified set should be removed from the current process signal mask.
1785 @end deftypevr
1786
1787 @comment signal.h
1788 @comment POSIX.1
1789 @deftypevr Macro int SIG_SETMASK
1790 The value of this macro is an integer suitable for use as the @var{how}
1791 argument to @code{sigprocmask}, to specify that the process signal mask
1792 should be set to the specified signal set.
1793 @end deftypevr
1794
1795 Temporary blocking of signals with @code{sigprocmask} is useful primarily
1796 when you want to lock out interrupts during critical parts
1797 of your code.  One example of this kind of situation is where you
1798 are accessing data that is shared with a signal handler.
1799
1800 As described in @ref{Defining a Signal Handler}, the most reliable way
1801 to have your program deal with a signal is to create an external,
1802 @code{volatile} variable and make your signal handler change its value.
1803 The problem arises when your program needs to access or modify this
1804 variable.  Even if you check the variable to see whether a signal has
1805 arrived immediately before you set it, another signal might still arrive
1806 in the meantime, and you will never know it was there.  You can avoid
1807 this problem by blocking the signal during the time you are performing
1808 the check and modification.
1809
1810 A related situation is where you have several variables or variables of
1811 types other than @code{sig_atomic_t} that are being manipulated by one
1812 or more signal handlers.  In this kind of situation, you want to be sure
1813 that operations on this data are performed as a complete unit.  You can
1814 implement a locking protocol for the data by temporarily blocking the
1815 signals that might otherwise cause the data to be modified.
1816
1817 Now for a simple example.  Suppose you establish a handler for
1818 @code{SIGALRM} signals that sets a flag whenever a signal arrives, and
1819 your main program checks this flag from time to time and then resets it.
1820 You can prevent additional @code{SIGALRM} signals from arriving in the
1821 meantime by wrapping the critical part of the code with calls to
1822 @code{sigprocmask}, like this:
1823
1824 @example
1825 /* @r{This variable is set by the SIGALRM signal handler.} */
1826 volatile sig_atomic_t flag = 0;
1827
1828 void main (void)
1829 @{
1830   sigset_t block_alarm;
1831
1832   @dots{}
1833
1834   /* @r{Initialize the signal mask.} */
1835   sigemptyset (&block_alarm);
1836   sigaddset (&block_alarm, SIGALRM);
1837
1838
1839   while (1) @{
1840
1841     /* @r{Check if a signal has arrived; if so, reset the flag.} */
1842     sigprocmask (SIG_BLOCK, &block_alarm, NULL);
1843     if (flag) @{
1844       @dots{}
1845       flag = 0;
1846       @}
1847     sigprocmask (SIG_UNBLOCK, &block_alarm, NULL);
1848
1849     @dots{}
1850   @}
1851 @}
1852 @end example
1853
1854 @node Blocking Signals in a Handler
1855 @subsection Blocking Signals in a Handler
1856 @cindex blocking signals, in a handler
1857
1858 When a signal handler is invoked, you usually want to let it run to
1859 completion before another signal arrives.  From the moment the
1860 handler starts until the moment it finishes, you must block signals
1861 that might confuse it or corrupt its data.
1862
1863 When a handler function is invoked on a signal, that signal is
1864 automatically blocked (in addition to any other signals that are already
1865 in the process's signal mask) during the time the handler is running.
1866 If you set up a handler for @code{SIGTSTP}, for instance, then the
1867 arrival of that signal forces further @code{SIGTSTP} signals to wait
1868 during the execution of the handler.
1869
1870 You can temporarily block additional signals when the handler is running
1871 by using the @code{sa_mask} member of the @code{sigaction} structure.
1872
1873 Here is an example:
1874
1875 @example
1876 #include <signal.h>
1877 #include <stddef.h>
1878
1879 void catch_stop ();
1880
1881 /* @r{Block all terminal-generated signals while handler runs.} */
1882 void install_handler (void)
1883 @{
1884   struct sigaction setup_action;
1885   sigset_t block_mask;
1886
1887   sigemptyset (&block_mask);
1888   sigaddset (&block_mask, SIGINT);
1889   sigaddset (&block_mask, SIGQUIT);
1890   sigaddset (&block_mask, SIGTSTP);
1891   setup_action.sa_handler = catch_stop;
1892   setup_action.sa_mask = block_mask;
1893   setup_action.sa_flags = 0;
1894   sigaction (SIGTSTP, &setup_action, NULL);
1895 @}
1896 @end example
1897
1898 You cannot remove signals from the process's current mask using this
1899 mechanism.  However, you can make calls to @code{sigprocmask} within
1900 your handler to put any mask you want in place.  In any case, when the
1901 handler returns, the system restores the mask that was in place before
1902 the handler was entered.
1903
1904
1905 @node Checking for Pending Signals
1906 @subsection Checking for Pending Signals
1907 @cindex pending signals, checking for
1908 @cindex blocked signals, checking for
1909 @cindex checking for pending signals
1910
1911 You can find out which signals are pending at any time by calling
1912 @code{sigpending}.  This function is declared in @file{signal.h}.
1913 @pindex signal.h
1914
1915 @comment signal.h
1916 @comment POSIX.1
1917 @deftypefun int sigpending (sigset_t *@var{set})
1918 The @code{sigpending} function stores information about pending signals
1919 in @var{set}.  If there is a pending signal that is blocked from
1920 delivery, then that signal is a member of the returned set.  (You can
1921 test whether a particular signal is a member of this set using
1922 @code{sigismember}; @pxref{Signal Sets}.)
1923
1924 The return value is @code{0} if successful, and @code{-1} on failure.
1925 @end deftypefun
1926
1927
1928 Here is an example.
1929
1930 @example
1931 #include <signal.h>
1932 #include <stddef.h>
1933
1934 sigset_t base_mask, waiting_mask;
1935
1936 sigemptyset (&base_mask);
1937 sigaddset (&base_mask, SIGINT);
1938 sigaddset (&base_mask, SIGTSTP);
1939
1940 /* @r{Block user interrupts while doing other processing.} */
1941 sigprocmask (SIG_SETMASK, &base_mask, NULL); 
1942 @dots{}
1943
1944 /* @r{After a while, check to see whether any signals are pending.} */
1945 sigpending (&waiting_mask);
1946 if (sigismember (&waiting_mask, SIGINT)) @{
1947   /* @r{User has tried to kill the process.} */
1948   @}
1949 else if (sigismember (&waiting_mask, SIGTSTP)) @{
1950   /* @r{User has tried to stop the process.} */
1951   @}
1952 @end example
1953
1954 Remember that if there is a particular signal pending for your process,
1955 additional signals of that same type that arrive in the meantime might
1956 be discarded.  For example, if a @code{SIGINT} signal is pending when
1957 another @code{SIGINT} signal arrives, your program will probably only
1958 see one of them when you unblock this signal.
1959
1960 @node Waiting for a Signal
1961 @section Waiting for a Signal
1962 @cindex waiting for a signal
1963 @cindex @code{sleep} function
1964 @cindex @code{pause} function
1965
1966 If your program is driven by external events, or uses signals for
1967 synchronization, there are times you might want to suspend execution
1968 until a signal arrives.  If you block the process in this way, it won't
1969 use any CPU time while it is waiting.
1970
1971 The @code{pause} and @code{sleep} functions are declared in the header
1972 file @file{unistd.h}, while @code{sigsuspend} is declared in
1973 @file{signal.h}.
1974 @pindex signal.h
1975 @pindex unistd.h
1976
1977 @comment unistd.h
1978 @comment POSIX.1
1979 @deftypefun int pause (void)
1980 The @code{pause} function suspends program execution until a signal
1981 arrives whose action is either to execute a handler function, or to
1982 terminate the process.
1983
1984 If the signal causes a handler function to be executed, then @code{pause}
1985 returns.  This is considered an unsuccessful return (since ``successful''
1986 behavior would be to suspend the program forever), so the return value
1987 is @code{-1}.
1988
1989 The following @code{errno} error conditions are defined for this function:
1990
1991 @table @code
1992 @item EINTR
1993 The function was interrupted by delivery of a signal.
1994 @end table
1995
1996 If the signal causes program termination, @code{pause} doesn't return
1997 (obviously).
1998 @end deftypefun
1999
2000 If you only want your program to delay execution for a limited period of
2001 time (as opposed to indefinitely), you can use the @code{sleep} function
2002 instead of @code{pause}.  A common situation is using @code{sleep} in a
2003 loop, to make the process ``wake up'' periodically to perform some
2004 actions.
2005
2006 @comment unistd.h
2007 @comment POSIX.1
2008 @deftypefun {unsigned int} sleep (unsigned int @var{seconds})
2009 The @code{sleep} function is like @code{pause}, except that execution
2010 is suspended only for the amount of time specified by the @var{seconds}
2011 argument instead of indefinitely.  
2012
2013 The @code{sleep} function might be implemented using an alarm;
2014 @pxref{Setting an Alarm}.  If another @code{SIGALRM} signal arrives
2015 during the time the process is sleeping, strange things can happen.
2016 Even if @code{SIGALRM} signals are being ignored or blocked when
2017 @code{sleep} is called, @code{sleep} might return prematurely on
2018 delivery of a @code{SIGALRM} signal.  If you have established a handler
2019 for @code{SIGALRM} signals and a @code{SIGALRM} signal is delivered
2020 while the process is sleeping, the action taken might be just to cause
2021 @code{sleep} to return instead of invoking your handler.  And, if
2022 @code{sleep} is interrupted by delivery of a signal whose handler messes
2023 with @code{SIGALRM} signals, things can really get confused.  In short,
2024 avoid messing with @code{SIGALRM} directly if you use @code{sleep}.
2025
2026 If @code{sleep} function returns because the requested time has
2027 elapsed, it returns a value of zero.  If it returns because of delivery
2028 of a signal, its return value is the remaining time in the sleep period.
2029 @end deftypefun
2030
2031 Watch out for checking to see whether a signal has been reported and
2032 then calling @code{pause} to wait for a signal if it hasn't arrived yet.
2033 The signal might actually arrive in between the two operations and your
2034 program will never wake up.  A better solution is to use
2035 @code{sigprocmask} to block signals while you check to see if a signal
2036 has arrived yet, and then use @code{sigsuspend} to both restore the
2037 original signal mask and suspend execution in one uninterruptable
2038 operation.
2039
2040 @comment signal.h
2041 @comment POSIX.1
2042 @deftypefun int sigsuspend (const sigset_t *@var{set})
2043 This function replaces the process's signal mask with @var{set} and then
2044 suspends the process until a signal is delivered whose action is either
2045 to terminate the process or invoke a signal handling function.  In other
2046 words, the program is effectively suspended until one of the signals that
2047 is not a member of @var{set} arrives.
2048
2049 If the process is woken up by deliver of a signal that invokes a handler
2050 function, and the handler function returns, then @code{sigsuspend} also
2051 returns.  It sets the process's signal mask back to what it was when
2052 @code{sigsuspend} was called.  
2053
2054 The return value and error conditions are the same as for @code{pause}.
2055 @end deftypefun
2056
2057 As an example of how these functions might be used, let's reconsider the
2058 program presented in @ref{Signaling Another Process}.  As originally
2059 written, this program does a busy wait for a @code{SIGUSR1} signal to
2060 arrive by sitting in a tight loop, checking a variable that is set by
2061 the signal handler, like this:
2062
2063 @example
2064 while (!usr_interrupt) @{@}
2065 @end example
2066
2067 Doing a busy wait is not really a good idea, since it wastes system 
2068 resources that could better be used by another process.  Having the
2069 process block until the signal arrives would be much better.
2070
2071 Naively, one might expect to rewrite this loop instead as simply:
2072
2073 @example
2074 while (!usr_interrupt)
2075   pause ();
2076 @end example
2077
2078 @noindent
2079 But this has a bug: the signal could arrive after the variable
2080 @code{usr_interrupt} is checked, but before the call to @code{pause}.
2081 In this case, the process would never wake up again.
2082
2083 To avoid this problem, you can use a combination of @code{sigprocmask}
2084 and @code{sigsuspend}, like this:
2085
2086 @example
2087 sigset_t mask, oldmask;
2088
2089 @dots{}
2090
2091 /* @r{Set up the mask of signals to temporarily block.} */ 
2092 sigemptyset (&mask); 
2093 sigaddset (&mask, SIGUSR1);
2094
2095 @dots{}
2096
2097 /* @r{Wait for a signal to arrive.} */
2098 sigprocmask (SIG_BLOCK, &mask, &oldmask);
2099 while (!usr_interrupt)
2100   sigsuspend (&oldmask);
2101 sigprocmask (SIG_UNBLOCK, &mask, NULL);
2102 @end example
2103
2104 This last piece of code is a little tricky.  The key point to remember
2105 here is that when @code{sigsuspend} returns, it resets the process's
2106 signal mask to be the original value from before the call to
2107 @code{sigsuspend} --- in this case, the @code{SIGUSR1} signal is once
2108 again blocked.  The second call to @code{sigprocmask} is
2109 necessary to explicitly unblock this signal.
2110
2111 One other point: you may be wondering why the @code{while} loop is
2112 necessary at all, since the program is apparently only waiting for one
2113 @code{SIGUSR1} signal.  The answer is that the mask passed to
2114 @code{sigsuspend} permits the process to be woken up by the delivery of
2115 other kinds of signals, as well --- for example, job control signals.
2116 If the process is woken up by a signal that doesn't set
2117 @code{usr_interrupt}, it just suspends itself again until the ``right''
2118 kind of signal eventually arrives.
2119
2120
2121 @node BSD Signal Handling
2122 @section BSD Signal Handling
2123
2124 This section describes signal handling functions included in the GNU C
2125 library for backward compability with BSD Unix.  In new programs, you
2126 should avoid these functions and use the POSIX-standard functions
2127 instead, because they are more general in some ways.
2128
2129 There are many similarities between the BSD and POSIX signal handling
2130 facilities, because the POSIX facilities were inspired by the BSD
2131 facilities.  Besides having different names for all the functions to
2132 avoid conflicts, the main differences between the two are:
2133
2134 @itemize @bullet
2135 @item
2136 BSD Unix represents signal masks as an @code{int} bit mask, rather than
2137 as a @code{sigset_t} object.
2138
2139 @item
2140 BSD Unix provides hooks that let you control whether signals interrupt
2141 system calls.  If a signal arrives during a system call (such as a read
2142 or write operation that blocks the process), it may either return with
2143 an @code{EINTR} error or be restarted.  POSIX provides no mechanism for
2144 controlling this, but BSD does.
2145 @cindex interrupted system call
2146
2147 @item
2148 BSD Unix has a concept of a @dfn{signal stack}.  This is an alternate
2149 stack that is used during the execution of signal handler functions,
2150 instead of its normal execution stack.
2151 @cindex signal stack
2152 @end itemize
2153
2154 These facilities are declared in @file{signal.h}.
2155 @pindex signal.h
2156
2157 @comment signal.h
2158 @comment BSD
2159 @deftypefn Macro int sigmask (int @var{signum})
2160 This macro returns a signal mask that has the bit for signal @var{signum}
2161 set.  You can bitwise-OR the results of several calls to @code{sigmask}
2162 together to specify more than one signal.  For example,
2163
2164 @example
2165 sigmask (SIGTSTP) | sigmask (SIGSTOP) |
2166 sigmask (SIGTTIN) | sigmask (SIGTTOU)
2167 @end example
2168
2169 @noindent
2170 specifies a mask that includes all the job-control stop signals.
2171 @end deftypefn
2172
2173 @comment signal.h
2174 @comment BSD
2175 @deftp {struct Type} sigvec
2176 This data type is the equivalent of @code{struct sigaction}
2177 (@pxref{Advanced Signal Handling}); it is used to specify signal actions
2178 to the @code{sigvec} function.  It contains the following members:
2179
2180 @table @code
2181 @item __sighandler_t sv_handler
2182 This is the handler function.
2183
2184 @item int sv_mask
2185 This is the mask of additional signals to be blocked while the handler
2186 function is being called.
2187
2188 @item int sv_flags
2189 This is a bit mask used to specify various flags which affect the
2190 behavior of the signal.  You can also refer to this field as
2191 @code{sv_onstack}.
2192 @end table
2193 @end deftp
2194
2195 These symbolic constants can be used to provide values for the
2196 @code{sv_flags} field of a @code{sigvec} structure.  This field is a bit
2197 mask value, so you bitwise-OR the flags of interest to you together.
2198
2199 @comment signal.h
2200 @comment BSD
2201 @deftypevr Macro int SV_ONSTACK
2202 This macro can be used with the @code{sv_flags} field of a @code{sigvec}
2203 structure, to specify that the signal stack should be used when delivering
2204 the signal.
2205 @end deftypevr
2206
2207 @comment signal.h
2208 @comment BSD
2209 @deftypevr Macro int SV_INTERRUPT
2210 This macro can be used with the @code{sv_flags} field of a @code{sigvec}
2211 structure, to specify that interrupted system calls should not be restarted.
2212 If this flag is set, interrupted system calls return with a @code{EINTR}
2213 error status.
2214 @end deftypevr
2215
2216 @comment signal.h
2217 @comment BSD
2218 @deftypevr Macro int SV_RESETHAND
2219 This macro can be used with the @code{sv_flags} field of a @code{sigvec}
2220 structure, to specify that the action for the signal should be reset back
2221 to @code{SIG_DFL} when the signal is received.
2222 @end deftypevr
2223
2224 @comment signal.h
2225 @comment BSD
2226 @deftypefun int sigvec (int @var{signum}, const struct sigvec *@var{action},struct sigvec *@var{old_action})
2227 This function is the equivalent of @code{sigaction} (@pxref{Advanced Signal
2228 Handling}); it installs the action @var{action} for the signal @var{signum},
2229 returning information about the previous action in effect for that signal
2230 in @var{old_action}.
2231 @end deftypefun
2232
2233 @comment signal.h
2234 @comment BSD
2235 @deftypefun int sigblock (int @var{mask})
2236 This function is the equivalent of @code{sigprocmask} (@pxref{Process
2237 Signal Mask}) with a @var{how} argument of @code{SIG_BLOCK}: it adds the
2238 signals specified by @var{mask} to the calling process's signal mask.
2239 The return value is the previous set of blocked signals.
2240 @end deftypefun
2241
2242 @comment signal.h
2243 @comment BSD
2244 @deftypefun int sigsetmask (int @var{mask})
2245 This function is the equivalent of @code{sigprocmask} (@pxref{Process
2246 Signal Mask}) with a @var{how} argument of @code{SIG_SETMASK}: it sets
2247 the calling process's signal mask to @var{mask}.  The return value is
2248 the previous set of blocked signals.
2249 @end deftypefun
2250
2251 @comment signal.h
2252 @comment BSD
2253 @deftypefun int sigpause (int @var{mask})
2254 This function is the equivalent of @code{sigsuspend} (@pxref{Waiting
2255 for a Signal}):  it sets the calling process's signal mask to @var{mask},
2256 and waits for a signal to arrive.  On return the previous set of blocked
2257 signals is restored.
2258 @end deftypefun
2259
2260 @comment signal.h
2261 @comment BSD
2262 @deftypefun int siginterrupt (int @var{signum}, int @var{interrupt})
2263 This function is used to change the system call interrupt behavior.  If
2264 @var{interrupt} is false, system calls are restarted when
2265 interrupted by receipt of the signal @var{signum}.  If @var{interrupt}
2266 is true, system calls return with a @code{EINTR} error when
2267 interrupted.
2268 @end deftypefun
2269
2270 @comment signal.h
2271 @comment BSD
2272 @deftp {struct Type} sigstack
2273 This structure describes a signal stack.  It contains the following members:
2274
2275 @table @code
2276 @item void *ss_sp
2277 This is the stack pointer.
2278
2279 @item int ss_onstack
2280 This field is true if the process is currently using this stack.
2281 @end table
2282 @end deftp
2283
2284 @comment signal.h
2285 @comment BSD
2286 @deftypefun int sigstack (const struct sigstack *@var{stack}, struct sigstack *@var{oldstack})
2287 The @code{sigstack} function selects an alternate stack for use during
2288 signal handling.  When a signal is received by the process and its
2289 action indicates that the signal stack is used, the system arranges a
2290 switch to the currently installed signal stack while the handler for
2291 that signal is executed.
2292
2293 If @var{oldstack} is not a null pointer, information about the currently
2294 installed signal stack is returned in the location it points to.  If
2295 @var{stack} is not a null pointer, then this is installed as the new
2296 stack for use by signal handlers.
2297
2298 The return value is @code{0} on success and @code{1} on failure.
2299 @end deftypefun
2300
2301 @strong{Incomplete:}  I don't think this is really enough information to
2302 tell people how to use this facility.  Help!