man2/signal.2

   1 .\" Copyright (c) 2000 Andries Brouwer <aeb@cwi.nl>
   2 .\" based on work by Rik Faith <faith@cs.unc.edu>
   3 .\" and Mike Battersby <mike@starbug.apana.org.au>.
   4 .\"
   5 .\" Permission is granted to make and distribute verbatim copies of this
   6 .\" manual provided the copyright notice and this permission notice are
   7 .\" preserved on all copies.
   8 .\"
   9 .\" Permission is granted to copy and distribute modified versions of this
  10 .\" manual under the conditions for verbatim copying, provided that the
  11 .\" entire resulting derived work is distributed under the terms of a
  12 .\" permission notice identical to this one.
  13 .\"
  14 .\" Since the Linux kernel and libraries are constantly changing, this
  15 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  16 .\" responsibility for errors or omissions, or for damages resulting from
  17 .\" the use of the information contained herein.  The author(s) may not
  18 .\" have taken the same level of care in the production of this manual,
  19 .\" which is licensed free of charge, as they might when working
  20 .\" professionally.
  21 .\"
  22 .\" Formatted or processed versions of this manual, if unaccompanied by
  23 .\" the source, must acknowledge the copyright and authors of this work.
  24 .\"
  25 .\" Modified 2004-11-19, mtk:
  26 .\" added pointer to sigaction.2 for details of ignoring SIGCHLD
  27 .\"
  28 .TH SIGNAL 2 2000-04-28 "Linux 2.2" "Linux Programmer's Manual"
  29 .SH NAME
  30 signal \- ANSI C signal handling
  31 .SH SYNOPSIS
  32 .B #include <signal.h>
  33 .sp
  34 .B typedef void (*sighandler_t)(int);
  35 .sp
  36 .BI "sighandler_t signal(int " signum ", sighandler_t " handler );
  37 .SH DESCRIPTION
  38 The
  39 .BR signal ()
  40 system call installs a new signal handler for the signal with number
  41 .IR signum .
  42 The signal handler is set to
  43 .I sighandler
  44 which may be a user specified function, or either
  45 .B SIG_IGN
  46 or
  47 .BR SIG_DFL .
  48
  49 Upon arrival of a signal with number
  50 .I signum
  51 the following happens.
  52 If the corresponding handler is set to
  53 .BR SIG_IGN ,
  54 then the signal is ignored.
  55 If the handler is set to
  56 .BR SIG_DFL ,
  57 then the default action associated with the signal (see
  58 .BR signal (7))
  59 occurs.
  60 Finally, if the handler is set to a function
  61 .I sighandler
  62 then first either the handler is reset to SIG_DFL
  63 or an implementation-dependent blocking of the signal
  64 is performed and next
  65 .I sighandler
  66 is called with argument
  67 .IR signum .
  68
  69 Using a signal handler function for a signal
  70 is called "catching the signal".
  71 The signals
  72 .B SIGKILL
  73 and
  74 .B SIGSTOP
  75 cannot be caught or ignored.
  76 .SH "RETURN VALUE"
  77 The
  78 .BR signal ()
  79 function returns the previous value of the signal handler, or
  80 .B SIG_ERR
  81 on error.
  82 .SH PORTABILITY
  83 The original Unix
  84 .BR signal ()
  85 would reset the handler to SIG_DFL, and System V
  86 (and the Linux kernel and libc4,5) does the same.
  87 On the other hand, BSD does not reset the handler, but blocks
  88 new instances of this signal from occurring during a call of the handler.
  89 The glibc2 library follows the BSD behaviour.
  90
  91 If one on a libc5 system includes
  92 .B "<bsd/signal.h>"
  93 instead of
  94 .B "<signal.h>"
  95 then
  96 .BR signal ()
  97 is redefined as
  98 .B __bsd_signal
  99 and signal has the BSD semantics. This is not recommended.
 100
 101 If one on a glibc2 system defines a feature test
 102 macro such as
 103 .B _XOPEN_SOURCE
 104 or uses a separate
 105 .B sysv_signal
 106 function, one obtains classical behaviour. This is not recommended.
 107
 108 Trying to change the semantics of this call using
 109 defines and includes is not a good idea. It is better to avoid
 110 .BR signal ()
 111 altogether, and use
 112 .BR sigaction (2)
 113 instead.
 114 .SH NOTES
 115 The effects of this call in a multi-threaded process are unspecified.
 116 .PP
 117 The routine
 118 .I handler
 119 must be very careful, since processing elsewhere was interrupted
 120 at some arbitrary point. POSIX has the concept of "safe function".
 121 If a signal interrupts an unsafe function, and
 122 .I handler
 123 calls an unsafe function, then the behavior is undefined. Safe
 124 functions are listed explicitly in the various standards.
 125 The POSIX 1003.1-2003 list is
 126
 127 _Exit()
 128 _exit()
 129 abort()
 130 accept()
 131 access()
 132 aio_error()
 133 aio_return()
 134 aio_suspend()
 135 alarm()
 136 bind()
 137 cfgetispeed()
 138 cfgetospeed()
 139 cfsetispeed()
 140 cfsetospeed()
 141 chdir()
 142 chmod()
 143 chown()
 144 clock_gettime()
 145 close()
 146 connect()
 147 creat()
 148 dup()
 149 dup2()
 150 execle()
 151 execve()
 152 fchmod()
 153 fchown()
 154 fcntl()
 155 fdatasync()
 156 fork()
 157 fpathconf()
 158 fstat()
 159 fsync()
 160 ftruncate()
 161 getegid()
 162 geteuid()
 163 getgid()
 164 getgroups()
 165 getpeername()
 166 getpgrp()
 167 getpid()
 168 getppid()
 169 getsockname()
 170 getsockopt()
 171 getuid()
 172 kill()
 173 link()
 174 listen()
 175 lseek()
 176 lstat()
 177 mkdir()
 178 mkfifo()
 179 open()
 180 pathconf()
 181 pause()
 182 pipe()
 183 poll()
 184 posix_trace_event()
 185 pselect()
 186 raise()
 187 read()
 188 readlink()
 189 recv()
 190 recvfrom()
 191 recvmsg()
 192 rename()
 193 rmdir()
 194 select()
 195 sem_post()
 196 send()
 197 sendmsg()
 198 sendto()
 199 setgid()
 200 setpgid()
 201 setsid()
 202 setsockopt()
 203 setuid()
 204 shutdown()
 205 sigaction()
 206 sigaddset()
 207 sigdelset()
 208 sigemptyset()
 209 sigfillset()
 210 sigismember()
 211 signal()
 212 sigpause()
 213 sigpending()
 214 sigprocmask()
 215 sigqueue()
 216 sigset()
 217 sigsuspend()
 218 sleep()
 219 socket()
 220 socketpair()
 221 stat()
 222 symlink()
 223 sysconf()
 224 tcdrain()
 225 tcflow()
 226 tcflush()
 227 tcgetattr()
 228 tcgetpgrp()
 229 tcsendbreak()
 230 tcsetattr()
 231 tcsetpgrp()
 232 time()
 233 timer_getoverrun()
 234 timer_gettime()
 235 timer_settime()
 236 times()
 237 umask()
 238 uname()
 239 unlink()
 240 utime()
 241 wait()
 242 waitpid()
 243 write().
 244 .PP
 245 According to POSIX, the behaviour of a process is undefined after it
 246 ignores a
 247 .BR SIGFPE ,
 248 .BR SIGILL ,
 249 or
 250 .B SIGSEGV
 251 signal that was not generated by the
 252 .BR kill (2)
 253 or the
 254 .BR raise (3)
 255 functions.
 256 Integer division by zero has undefined result.
 257 On some architectures it will generate a
 258 .B SIGFPE
 259 signal.
 260 (Also dividing the most negative integer by \-1 may generate
 261 .BR SIGFPE .)
 262 Ignoring this signal might lead to an endless loop.
 263 .PP
 264 See
 265 .BR sigaction (2)
 266 for details on what happens when
 267 .B SIGCHLD
 268 is set to
 269 .BR SIG_IGN .
 270 .PP
 271 The use of
 272 .B sighandler_t
 273 is a GNU extension.
 274 Various versions of libc predefine this type; libc4 and libc5 define
 275 .IR SignalHandler ,
 276 glibc defines
 277 .I sig_t
 278 and, when
 279 .B _GNU_SOURCE
 280 is defined, also
 281 .IR sighandler_t .
 282 .SH "CONFORMING TO"
 283 ANSI C
 284 .SH "SEE ALSO"
 285 .BR kill (1),
 286 .BR alarm (2),
 287 .BR kill (2),
 288 .BR pause (2),
 289 .BR sigaction (2),
 290 .BR sigpending (2),
 291 .BR sigprocmask (2),
 292 .BR sigqueue (2),
 293 .BR sigsuspend (2),
 294 .BR killpg (3),
 295 .BR raise (3),
 296 .BR sigsetops (3),
 297 .BR sigvec (3),
 298 .BR feature_test_macros (7),
 299 .BR signal (7)