man2/signal.2

   1 .\" Copyright (c) 2000 Andries Brouwer <aeb@cwi.nl>
   2 .\" and Copyright (c) 2007 Michael Kerrisk <mtk.manpages@gmail.com>
   3 .\" and Copyright (c) 2008, Linux Foundation, written by Michael Kerrisk
   4 .\"      <mtk.manpages@gmail.com>
   5 .\" based on work by Rik Faith <faith@cs.unc.edu>
   6 .\" and Mike Battersby <mike@starbug.apana.org.au>.
   7 .\"
   8 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   9 .\"
  10 .\" Modified 2004-11-19, mtk:
  11 .\" added pointer to sigaction.2 for details of ignoring SIGCHLD
  12 .\" 2007-06-03, mtk: strengthened portability warning, and rewrote
  13 .\"     various sections.
  14 .\" 2008-07-11, mtk: rewrote and expanded portability discussion.
  15 .\"
  16 .TH SIGNAL 2 2021-03-22 "Linux man-pages (unreleased)" "Linux Programmer's Manual"
  17 .SH NAME
  18 signal \- ANSI C signal handling
  19 .SH LIBRARY
  20 Standard C library
  21 .RI ( libc ", " \-lc )
  22 .SH SYNOPSIS
  23 .nf
  24 .B #include <signal.h>
  25 .PP
  26 .B typedef void (*sighandler_t)(int);
  27 .PP
  28 .BI "sighandler_t signal(int " signum ", sighandler_t " handler );
  29 .fi
  30 .SH DESCRIPTION
  31 .BR WARNING :
  32 the behavior of
  33 .BR signal ()
  34 varies across UNIX versions,
  35 and has also varied historically across different versions of Linux.
  36 \fBAvoid its use\fP: use
  37 .BR sigaction (2)
  38 instead.
  39 See \fIPortability\fP below.
  40 .PP
  41 .BR signal ()
  42 sets the disposition of the signal
  43 .I signum
  44 to
  45 .IR handler ,
  46 which is either
  47 .BR SIG_IGN ,
  48 .BR SIG_DFL ,
  49 or the address of a programmer-defined function (a "signal handler").
  50 .PP
  51 If the signal
  52 .I signum
  53 is delivered to the process, then one of the following happens:
  54 .TP 3
  55 *
  56 If the disposition is set to
  57 .BR SIG_IGN ,
  58 then the signal is ignored.
  59 .TP
  60 *
  61 If the disposition is set to
  62 .BR SIG_DFL ,
  63 then the default action associated with the signal (see
  64 .BR signal (7))
  65 occurs.
  66 .TP
  67 *
  68 If the disposition is set to a function,
  69 then first either the disposition is reset to
  70 .BR SIG_DFL ,
  71 or the signal is blocked (see \fIPortability\fP below), and then
  72 .I handler
  73 is called with argument
  74 .IR signum .
  75 If invocation of the handler caused the signal to be blocked,
  76 then the signal is unblocked upon return from the handler.
  77 .PP
  78 The signals
  79 .B SIGKILL
  80 and
  81 .B SIGSTOP
  82 cannot be caught or ignored.
  83 .SH RETURN VALUE
  84 .BR signal ()
  85 returns the previous value of the signal handler.
  86 On failure, it returns
  87 .BR SIG_ERR ,
  88 and
  89 .I errno
  90 is set to indicate the error.
  91 .SH ERRORS
  92 .TP
  93 .B EINVAL
  94 .I signum
  95 is invalid.
  96 .SH STANDARDS
  97 POSIX.1-2001, POSIX.1-2008, C89, C99.
  98 .SH NOTES
  99 The effects of
 100 .BR signal ()
 101 in a multithreaded process are unspecified.
 102 .PP
 103 According to POSIX, the behavior of a process is undefined after it
 104 ignores a
 105 .BR SIGFPE ,
 106 .BR SIGILL ,
 107 or
 108 .B SIGSEGV
 109 signal that was not generated by
 110 .BR kill (2)
 111 or
 112 .BR raise (3).
 113 Integer division by zero has undefined result.
 114 On some architectures it will generate a
 115 .B SIGFPE
 116 signal.
 117 (Also dividing the most negative integer by \-1 may generate
 118 .BR SIGFPE .)
 119 Ignoring this signal might lead to an endless loop.
 120 .PP
 121 See
 122 .BR sigaction (2)
 123 for details on what happens when the disposition
 124 .B SIGCHLD
 125 is set to
 126 .BR SIG_IGN .
 127 .PP
 128 See
 129 .BR signal\-safety (7)
 130 for a list of the async-signal-safe functions that can be
 131 safely called from inside a signal handler.
 132 .PP
 133 The use of
 134 .I sighandler_t
 135 is a GNU extension, exposed if
 136 .B _GNU_SOURCE
 137 is defined;
 138 .\" libc4 and libc5 define
 139 .\" .IR SignalHandler ;
 140 glibc also defines (the BSD-derived)
 141 .I sig_t
 142 if
 143 .B _BSD_SOURCE
 144 (glibc 2.19 and earlier)
 145 or
 146 .B _DEFAULT_SOURCE
 147 (glibc 2.19 and later)
 148 is defined.
 149 Without use of such a type, the declaration of
 150 .BR signal ()
 151 is the somewhat harder to read:
 152 .PP
 153 .in +4n
 154 .EX
 155 .BI "void ( *" signal "(int " signum ", void (*" handler ")(int)) ) (int);"
 156 .EE
 157 .in
 158 .SS Portability
 159 The only portable use of
 160 .BR signal ()
 161 is to set a signal's disposition to
 162 .B SIG_DFL
 163 or
 164 .BR SIG_IGN .
 165 The semantics when using
 166 .BR signal ()
 167 to establish a signal handler vary across systems
 168 (and POSIX.1 explicitly permits this variation);
 169 .B do not use it for this purpose.
 170 .PP
 171 POSIX.1 solved the portability mess by specifying
 172 .BR sigaction (2),
 173 which provides explicit control of the semantics when a
 174 signal handler is invoked; use that interface instead of
 175 .BR signal ().
 176 .PP
 177 In the original UNIX systems, when a handler that was established using
 178 .BR signal ()
 179 was invoked by the delivery of a signal,
 180 the disposition of the signal would be reset to
 181 .BR SIG_DFL ,
 182 and the system did not block delivery of further instances of the signal.
 183 This is equivalent to calling
 184 .BR sigaction (2)
 185 with the following flags:
 186 .PP
 187 .in +4n
 188 .EX
 189 sa.sa_flags = SA_RESETHAND | SA_NODEFER;
 190 .EE
 191 .in
 192 .PP
 193 System\ V also provides these semantics for
 194 .BR signal ().
 195 This was bad because the signal might be delivered again
 196 before the handler had a chance to reestablish itself.
 197 Furthermore, rapid deliveries of the same signal could
 198 result in recursive invocations of the handler.
 199 .PP
 200 BSD improved on this situation, but unfortunately also
 201 changed the semantics of the existing
 202 .BR signal ()
 203 interface while doing so.
 204 On BSD, when a signal handler is invoked,
 205 the signal disposition is not reset,
 206 and further instances of the signal are blocked from
 207 being delivered while the handler is executing.
 208 Furthermore, certain blocking system calls are automatically
 209 restarted if interrupted by a signal handler (see
 210 .BR signal (7)).
 211 The BSD semantics are equivalent to calling
 212 .BR sigaction (2)
 213 with the following flags:
 214 .PP
 215 .in +4n
 216 .EX
 217 sa.sa_flags = SA_RESTART;
 218 .EE
 219 .in
 220 .PP
 221 The situation on Linux is as follows:
 222 .IP * 2
 223 The kernel's
 224 .BR signal ()
 225 system call provides System\ V semantics.
 226 .IP *
 227 By default, in glibc 2 and later, the
 228 .BR signal ()
 229 wrapper function does not invoke the kernel system call.
 230 Instead, it calls
 231 .BR sigaction (2)
 232 using flags that supply BSD semantics.
 233 This default behavior is provided as long as a suitable
 234 feature test macro is defined:
 235 .B _BSD_SOURCE
 236 on glibc 2.19 and earlier or
 237 .B _DEFAULT_SOURCE
 238 in glibc 2.19 and later.
 239 (By default, these macros are defined; see
 240 .BR feature_test_macros (7)
 241 for details.)
 242 If such a feature test macro is not defined, then
 243 .BR signal ()
 244 provides System\ V semantics.
 245 .\"
 246 .\" System V semantics are also provided if one uses the separate
 247 .\" .BR sysv_signal (3)
 248 .\" function.
 249 .\" .IP *
 250 .\" The
 251 .\" .BR signal ()
 252 .\" function in Linux libc4 and libc5 provide System\ V semantics.
 253 .\" If one on a libc5 system includes
 254 .\" .I <bsd/signal.h>
 255 .\" instead of
 256 .\" .IR <signal.h> ,
 257 .\" then
 258 .\" .BR signal ()
 259 .\" provides BSD semantics.
 260 .SH SEE ALSO
 261 .BR kill (1),
 262 .BR alarm (2),
 263 .BR kill (2),
 264 .BR pause (2),
 265 .BR sigaction (2),
 266 .BR signalfd (2),
 267 .BR sigpending (2),
 268 .BR sigprocmask (2),
 269 .BR sigsuspend (2),
 270 .BR bsd_signal (3),
 271 .BR killpg (3),
 272 .BR raise (3),
 273 .BR siginterrupt (3),
 274 .BR sigqueue (3),
 275 .BR sigsetops (3),
 276 .BR sigvec (3),
 277 .BR sysv_signal (3),
 278 .BR signal (7)