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 (date) "Linux man-pages (unreleased)"
  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 .P
  26 .B typedef void (*sighandler_t)(int);
  27 .P
  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 .P
  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 .P
  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 .P
  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 VERSIONS
  97 The use of
  98 .I sighandler_t
  99 is a GNU extension, exposed if
 100 .B _GNU_SOURCE
 101 is defined;
 102 .\" libc4 and libc5 define
 103 .\" .IR SignalHandler ;
 104 glibc also defines (the BSD-derived)
 105 .I sig_t
 106 if
 107 .B _BSD_SOURCE
 108 (glibc 2.19 and earlier)
 109 or
 110 .B _DEFAULT_SOURCE
 111 (glibc 2.19 and later)
 112 is defined.
 113 Without use of such a type, the declaration of
 114 .BR signal ()
 115 is the somewhat harder to read:
 116 .P
 117 .in +4n
 118 .EX
 119 .BI "void ( *" signal "(int " signum ", void (*" handler ")(int)) ) (int);"
 120 .EE
 121 .in
 122 .SS Portability
 123 The only portable use of
 124 .BR signal ()
 125 is to set a signal's disposition to
 126 .B SIG_DFL
 127 or
 128 .BR SIG_IGN .
 129 The semantics when using
 130 .BR signal ()
 131 to establish a signal handler vary across systems
 132 (and POSIX.1 explicitly permits this variation);
 133 .B do not use it for this purpose.
 134 .P
 135 POSIX.1 solved the portability mess by specifying
 136 .BR sigaction (2),
 137 which provides explicit control of the semantics when a
 138 signal handler is invoked; use that interface instead of
 139 .BR signal ().
 140 .SH STANDARDS
 141 C11, POSIX.1-2008.
 142 .SH HISTORY
 143 C89, POSIX.1-2001.
 144 .P
 145 In the original UNIX systems, when a handler that was established using
 146 .BR signal ()
 147 was invoked by the delivery of a signal,
 148 the disposition of the signal would be reset to
 149 .BR SIG_DFL ,
 150 and the system did not block delivery of further instances of the signal.
 151 This is equivalent to calling
 152 .BR sigaction (2)
 153 with the following flags:
 154 .P
 155 .in +4n
 156 .EX
 157 sa.sa_flags = SA_RESETHAND | SA_NODEFER;
 158 .EE
 159 .in
 160 .P
 161 System\ V also provides these semantics for
 162 .BR signal ().
 163 This was bad because the signal might be delivered again
 164 before the handler had a chance to reestablish itself.
 165 Furthermore, rapid deliveries of the same signal could
 166 result in recursive invocations of the handler.
 167 .P
 168 BSD improved on this situation, but unfortunately also
 169 changed the semantics of the existing
 170 .BR signal ()
 171 interface while doing so.
 172 On BSD, when a signal handler is invoked,
 173 the signal disposition is not reset,
 174 and further instances of the signal are blocked from
 175 being delivered while the handler is executing.
 176 Furthermore, certain blocking system calls are automatically
 177 restarted if interrupted by a signal handler (see
 178 .BR signal (7)).
 179 The BSD semantics are equivalent to calling
 180 .BR sigaction (2)
 181 with the following flags:
 182 .P
 183 .in +4n
 184 .EX
 185 sa.sa_flags = SA_RESTART;
 186 .EE
 187 .in
 188 .P
 189 The situation on Linux is as follows:
 190 .IP \[bu] 3
 191 The kernel's
 192 .BR signal ()
 193 system call provides System\ V semantics.
 194 .IP \[bu]
 195 By default, in glibc 2 and later, the
 196 .BR signal ()
 197 wrapper function does not invoke the kernel system call.
 198 Instead, it calls
 199 .BR sigaction (2)
 200 using flags that supply BSD semantics.
 201 This default behavior is provided as long as a suitable
 202 feature test macro is defined:
 203 .B _BSD_SOURCE
 204 on glibc 2.19 and earlier or
 205 .B _DEFAULT_SOURCE
 206 in glibc 2.19 and later.
 207 (By default, these macros are defined; see
 208 .BR feature_test_macros (7)
 209 for details.)
 210 If such a feature test macro is not defined, then
 211 .BR signal ()
 212 provides System\ V semantics.
 213 .\"
 214 .\" System V semantics are also provided if one uses the separate
 215 .\" .BR sysv_signal (3)
 216 .\" function.
 217 .\" .IP \[bu]
 218 .\" The
 219 .\" .BR signal ()
 220 .\" function in Linux libc4 and libc5 provide System\ V semantics.
 221 .\" If one on a libc5 system includes
 222 .\" .I <bsd/signal.h>
 223 .\" instead of
 224 .\" .IR <signal.h> ,
 225 .\" then
 226 .\" .BR signal ()
 227 .\" provides BSD semantics.
 228 .SH NOTES
 229 The effects of
 230 .BR signal ()
 231 in a multithreaded process are unspecified.
 232 .P
 233 According to POSIX, the behavior of a process is undefined after it
 234 ignores a
 235 .BR SIGFPE ,
 236 .BR SIGILL ,
 237 or
 238 .B SIGSEGV
 239 signal that was not generated by
 240 .BR kill (2)
 241 or
 242 .BR raise (3).
 243 Integer division by zero has undefined result.
 244 On some architectures it will generate a
 245 .B SIGFPE
 246 signal.
 247 (Also dividing the most negative integer by \-1 may generate
 248 .BR SIGFPE .)
 249 Ignoring this signal might lead to an endless loop.
 250 .P
 251 See
 252 .BR sigaction (2)
 253 for details on what happens when the disposition
 254 .B SIGCHLD
 255 is set to
 256 .BR SIG_IGN .
 257 .P
 258 See
 259 .BR signal\-safety (7)
 260 for a list of the async-signal-safe functions that can be
 261 safely called from inside a signal handler.
 262 .SH SEE ALSO
 263 .BR kill (1),
 264 .BR alarm (2),
 265 .BR kill (2),
 266 .BR pause (2),
 267 .BR sigaction (2),
 268 .BR signalfd (2),
 269 .BR sigpending (2),
 270 .BR sigprocmask (2),
 271 .BR sigsuspend (2),
 272 .BR bsd_signal (3),
 273 .BR killpg (3),
 274 .BR raise (3),
 275 .BR siginterrupt (3),
 276 .BR sigqueue (3),
 277 .BR sigsetops (3),
 278 .BR sigvec (3),
 279 .BR sysv_signal (3),
 280 .BR signal (7)