1#
2#Copyright (c) 1994 Cygnus Support.
3#All rights reserved.
4#
5#Redistribution and use in source and binary forms are permitted
6#provided that the above copyright notice and this paragraph are
7#duplicated in all such forms and that any documentation,
8#and/or other materials related to such
9#distribution and use acknowledge that the software was developed
10#at Cygnus Support, Inc.  Cygnus Support, Inc. may not be used to
11#endorse or promote products derived from this software without
12#specific prior written permission.
13#THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR
14#IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
15#WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
16
17@node Signals
18@chapter Signal Handling (@file{signal.h})
19
20A @dfn{signal} is an event that interrupts the normal flow of control
21in your program.  Your operating environment normally defines the full
22set of signals available (see @file{sys/signal.h}), as well as the
23default means of dealing with them---typically, either printing an
24error message and aborting your program, or ignoring the signal.
25
26All systems support at least the following signals:
27@table @code
28@item SIGABRT
29Abnormal termination of a program; raised by the @code{abort} function.
30
31@item SIGFPE
32A domain error in arithmetic, such as overflow, or division by zero.
33
34@item SIGILL
35Attempt to execute as a function data that is not executable.
36
37@item SIGINT
38Interrupt; an interactive attention signal.
39
40@item SIGSEGV
41An attempt to access a memory location that is not available.
42
43@item SIGTERM
44A request that your program end execution.
45@end table
46
47Two functions are available for dealing with asynchronous
48signals---one to allow your program to send signals to itself (this is
49called @dfn{raising} a signal), and one to specify subroutines (called
50@dfn{handlers} to handle particular signals that you anticipate may
51occur---whether raised by your own program or the operating environment.
52
53To support these functions, @file{signal.h} defines three macros:
54
55@table @code
56@item SIG_DFL
57Used with the @code{signal} function in place of a pointer to a
58handler subroutine, to select the operating environment's default
59handling of a signal.
60
61@item SIG_IGN
62Used with the @code{signal} function in place of a pointer to a
63handler, to ignore a particular signal.
64
65@item SIG_ERR
66Returned by the @code{signal} function in place of a pointer to a
67handler, to indicate that your request to set up a handler could not
68be honored for some reason.
69@end table
70
71@file{signal.h} also defines an integral type, @code{sig_atomic_t}.
72This type is not used in any function declarations; it exists only to
73allow your signal handlers to declare a static storage location where
74they may store a signal value.  (Static storage is not otherwise
75reliable from signal handlers.)
76
77@menu
78* psignal:: Print a signal message to standard error
79* raise::   Send a signal
80* sig2str:: Translate between signal number and name
81* signal::  Specify handler subroutine for a signal
82@end menu
83
84@page
85@include signal/psignal.def
86
87@page
88@include signal/raise.def
89
90@page
91@include signal/sig2str.def
92
93@page
94@include signal/signal.def
95