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 .TH SIGNAL 2 2000-04-28 "Linux 2.2" "Linux Programmer's Manual"
  26 .SH NAME
  27 signal \- ANSI C signal handling
  28 .SH SYNOPSIS
  29 .B #include <signal.h>
  30 .sp
  31 .B typedef void (*sighandler_t)(int);
  32 .sp
  33 .BI "sighandler_t signal(int " signum ", sighandler_t " handler );
  34 .SH DESCRIPTION
  35 The
  36 .BR signal ()
  37 system call installs a new signal handler for the signal with number
  38 .IR signum .
  39 The signal handler is set to
  40 .I sighandler
  41 which may be a user specified function, or either
  42 .B SIG_IGN
  43 or
  44 .BR SIG_DFL .
  45
  46 Upon arrival of a signal with number
  47 .I signum
  48 the following happens.
  49 If the corresponding handler is set to
  50 .BR SIG_IGN ,
  51 then the signal is ignored.
  52 If the handler is set to
  53 .BR SIG_DFL ,
  54 then the default action associated to the signal (see
  55 .BR signal (7))
  56 occurs.
  57 Finally, if the handler is set to a function
  58 .I sighandler
  59 then first either the handler is reset to SIG_DFL
  60 or an implementation-dependent blocking of the signal
  61 is performed and next
  62 .I sighandler
  63 is called with argument
  64 .IR signum .
  65
  66 Using a signal handler function for a signal
  67 is called "catching the signal".
  68 The signals
  69 .B SIGKILL
  70 and
  71 .B SIGSTOP
  72 cannot be caught or ignored.
  73
  74 .SH "RETURN VALUE"
  75 The
  76 .BR signal ()
  77 function returns the previous value of the signal handler, or
  78 .B SIG_ERR
  79 on error.
  80
  81 .SH PORTABILITY
  82 The original Unix
  83 .BR signal ()
  84 would reset the handler to SIG_DFL, and System V
  85 (and the Linux kernel and libc4,5) does the same.
  86 On the other hand, BSD does not reset the handler, but blocks
  87 new instances of this signal from occurring during a call of the handler.
  88 The glibc2 library follows the BSD behaviour.
  89
  90 If one on a libc5 system includes
  91 .B "<bsd/signal.h>"
  92 instead of
  93 .B "<signal.h>"
  94 then
  95 .B signal
  96 is redefined as
  97 .B __bsd_signal
  98 and signal has the BSD semantics. This is not recommended.
  99
 100 If one on a glibc2 system defines a feature test
 101 macro such as
 102 .B _XOPEN_SOURCE
 103 or uses a separate
 104 .B sysv_signal
 105 function, one obtains classical behaviour. This is not recommended.
 106
 107 Trying to change the semantics of this call using
 108 defines and includes is not a good idea. It is better to avoid
 109 .B signal
 110 altogether, and use
 111 .BR sigaction (2)
 112 instead.
 113
 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 According to POSIX (3.3.1.3) it is unspecified what happens when
 265 .B SIGCHLD
 266 is set to
 267 .BR SIG_IGN .
 268 Here the BSD and SYSV behaviours differ, causing BSD software
 269 that sets the action for
 270 .B SIGCHLD
 271 to
 272 .B SIG_IGN
 273 to fail on Linux.
 274 .PP
 275 The use of
 276 .B sighandler_t
 277 is a GNU extension.
 278 Various versions of libc predefine this type; libc4 and libc5 define
 279 .IR SignalHandler ,
 280 glibc defines
 281 .I sig_t
 282 and, when
 283 .B _GNU_SOURCE
 284 is defined, also
 285 .IR sighandler_t .
 286 .SH "CONFORMING TO"
 287 ANSI C
 288
 289 .SH "SEE ALSO"
 290 .BR kill (1),
 291 .BR alarm (2),
 292 .BR kill (2),
 293 .BR killpg (2),
 294 .BR pause (2),
 295 .BR sigaction (2),
 296 .BR sigvec (2),
 297 .BR raise (3),
 298 .BR sigsetops (3),
 299 .BR signal (7)