1 :mod:`signal` --- Set handlers for asynchronous events 2 ====================================================== 3 4 .. module:: signal 5 :synopsis: Set handlers for asynchronous events. 6 7 -------------- 8 9 This module provides mechanisms to use signal handlers in Python. 10 11 12 General rules 13 ------------- 14 15 The :func:`signal.signal` function allows defining custom handlers to be 16 executed when a signal is received. A small number of default handlers are 17 installed: :const:`SIGPIPE` is ignored (so write errors on pipes and sockets 18 can be reported as ordinary Python exceptions) and :const:`SIGINT` is 19 translated into a :exc:`KeyboardInterrupt` exception. 20 21 A handler for a particular signal, once set, remains installed until it is 22 explicitly reset (Python emulates the BSD style interface regardless of the 23 underlying implementation), with the exception of the handler for 24 :const:`SIGCHLD`, which follows the underlying implementation. 25 26 27 Execution of Python signal handlers 28 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 29 30 A Python signal handler does not get executed inside the low-level (C) signal 31 handler. Instead, the low-level signal handler sets a flag which tells the 32 :term:`virtual machine` to execute the corresponding Python signal handler 33 at a later point(for example at the next :term:`bytecode` instruction). 34 This has consequences: 35 36 * It makes little sense to catch synchronous errors like :const:`SIGFPE` or 37 :const:`SIGSEGV` that are caused by an invalid operation in C code. Python 38 will return from the signal handler to the C code, which is likely to raise 39 the same signal again, causing Python to apparently hang. From Python 3.3 40 onwards, you can use the :mod:`faulthandler` module to report on synchronous 41 errors. 42 43 * A long-running calculation implemented purely in C (such as regular 44 expression matching on a large body of text) may run uninterrupted for an 45 arbitrary amount of time, regardless of any signals received. The Python 46 signal handlers will be called when the calculation finishes. 47 48 49 .. _signals-and-threads: 50 51 52 Signals and threads 53 ^^^^^^^^^^^^^^^^^^^ 54 55 Python signal handlers are always executed in the main Python thread, 56 even if the signal was received in another thread. This means that signals 57 can't be used as a means of inter-thread communication. You can use 58 the synchronization primitives from the :mod:`threading` module instead. 59 60 Besides, only the main thread is allowed to set a new signal handler. 61 62 63 Module contents 64 --------------- 65 66 .. versionchanged:: 3.5 67 signal (SIG*), handler (:const:`SIG_DFL`, :const:`SIG_IGN`) and sigmask 68 (:const:`SIG_BLOCK`, :const:`SIG_UNBLOCK`, :const:`SIG_SETMASK`) 69 related constants listed below were turned into 70 :class:`enums <enum.IntEnum>`. 71 :func:`getsignal`, :func:`pthread_sigmask`, :func:`sigpending` and 72 :func:`sigwait` functions return human-readable 73 :class:`enums <enum.IntEnum>`. 74 75 76 The variables defined in the :mod:`signal` module are: 77 78 79 .. data:: SIG_DFL 80 81 This is one of two standard signal handling options; it will simply perform 82 the default function for the signal. For example, on most systems the 83 default action for :const:`SIGQUIT` is to dump core and exit, while the 84 default action for :const:`SIGCHLD` is to simply ignore it. 85 86 87 .. data:: SIG_IGN 88 89 This is another standard signal handler, which will simply ignore the given 90 signal. 91 92 93 .. data:: SIG* 94 95 All the signal numbers are defined symbolically. For example, the hangup signal 96 is defined as :const:`signal.SIGHUP`; the variable names are identical to the 97 names used in C programs, as found in ``<signal.h>``. The Unix man page for 98 ':c:func:`signal`' lists the existing signals (on some systems this is 99 :manpage:`signal(2)`, on others the list is in :manpage:`signal(7)`). Note that 100 not all systems define the same set of signal names; only those names defined by 101 the system are defined by this module. 102 103 104 .. data:: CTRL_C_EVENT 105 106 The signal corresponding to the :kbd:`Ctrl+C` keystroke event. This signal can 107 only be used with :func:`os.kill`. 108 109 Availability: Windows. 110 111 .. versionadded:: 3.2 112 113 114 .. data:: CTRL_BREAK_EVENT 115 116 The signal corresponding to the :kbd:`Ctrl+Break` keystroke event. This signal can 117 only be used with :func:`os.kill`. 118 119 Availability: Windows. 120 121 .. versionadded:: 3.2 122 123 124 .. data:: NSIG 125 126 One more than the number of the highest signal number. 127 128 129 .. data:: ITIMER_REAL 130 131 Decrements interval timer in real time, and delivers :const:`SIGALRM` upon 132 expiration. 133 134 135 .. data:: ITIMER_VIRTUAL 136 137 Decrements interval timer only when the process is executing, and delivers 138 SIGVTALRM upon expiration. 139 140 141 .. data:: ITIMER_PROF 142 143 Decrements interval timer both when the process executes and when the 144 system is executing on behalf of the process. Coupled with ITIMER_VIRTUAL, 145 this timer is usually used to profile the time spent by the application 146 in user and kernel space. SIGPROF is delivered upon expiration. 147 148 149 .. data:: SIG_BLOCK 150 151 A possible value for the *how* parameter to :func:`pthread_sigmask` 152 indicating that signals are to be blocked. 153 154 .. versionadded:: 3.3 155 156 .. data:: SIG_UNBLOCK 157 158 A possible value for the *how* parameter to :func:`pthread_sigmask` 159 indicating that signals are to be unblocked. 160 161 .. versionadded:: 3.3 162 163 .. data:: SIG_SETMASK 164 165 A possible value for the *how* parameter to :func:`pthread_sigmask` 166 indicating that the signal mask is to be replaced. 167 168 .. versionadded:: 3.3 169 170 171 The :mod:`signal` module defines one exception: 172 173 .. exception:: ItimerError 174 175 Raised to signal an error from the underlying :func:`setitimer` or 176 :func:`getitimer` implementation. Expect this error if an invalid 177 interval timer or a negative time is passed to :func:`setitimer`. 178 This error is a subtype of :exc:`OSError`. 179 180 .. versionadded:: 3.3 181 This error used to be a subtype of :exc:`IOError`, which is now an 182 alias of :exc:`OSError`. 183 184 185 The :mod:`signal` module defines the following functions: 186 187 188 .. function:: alarm(time) 189 190 If *time* is non-zero, this function requests that a :const:`SIGALRM` signal be 191 sent to the process in *time* seconds. Any previously scheduled alarm is 192 canceled (only one alarm can be scheduled at any time). The returned value is 193 then the number of seconds before any previously set alarm was to have been 194 delivered. If *time* is zero, no alarm is scheduled, and any scheduled alarm is 195 canceled. If the return value is zero, no alarm is currently scheduled. (See 196 the Unix man page :manpage:`alarm(2)`.) Availability: Unix. 197 198 199 .. function:: getsignal(signalnum) 200 201 Return the current signal handler for the signal *signalnum*. The returned value 202 may be a callable Python object, or one of the special values 203 :const:`signal.SIG_IGN`, :const:`signal.SIG_DFL` or :const:`None`. Here, 204 :const:`signal.SIG_IGN` means that the signal was previously ignored, 205 :const:`signal.SIG_DFL` means that the default way of handling the signal was 206 previously in use, and ``None`` means that the previous signal handler was not 207 installed from Python. 208 209 210 .. function:: pause() 211 212 Cause the process to sleep until a signal is received; the appropriate handler 213 will then be called. Returns nothing. Not on Windows. (See the Unix man page 214 :manpage:`signal(2)`.) 215 216 See also :func:`sigwait`, :func:`sigwaitinfo`, :func:`sigtimedwait` and 217 :func:`sigpending`. 218 219 220 .. function:: pthread_kill(thread_id, signalnum) 221 222 Send the signal *signalnum* to the thread *thread_id*, another thread in the 223 same process as the caller. The target thread can be executing any code 224 (Python or not). However, if the target thread is executing the Python 225 interpreter, the Python signal handlers will be :ref:`executed by the main 226 thread <signals-and-threads>`. Therefore, the only point of sending a 227 signal to a particular Python thread would be to force a running system call 228 to fail with :exc:`InterruptedError`. 229 230 Use :func:`threading.get_ident()` or the :attr:`~threading.Thread.ident` 231 attribute of :class:`threading.Thread` objects to get a suitable value 232 for *thread_id*. 233 234 If *signalnum* is 0, then no signal is sent, but error checking is still 235 performed; this can be used to check if the target thread is still running. 236 237 Availability: Unix (see the man page :manpage:`pthread_kill(3)` for further 238 information). 239 240 See also :func:`os.kill`. 241 242 .. versionadded:: 3.3 243 244 245 .. function:: pthread_sigmask(how, mask) 246 247 Fetch and/or change the signal mask of the calling thread. The signal mask 248 is the set of signals whose delivery is currently blocked for the caller. 249 Return the old signal mask as a set of signals. 250 251 The behavior of the call is dependent on the value of *how*, as follows. 252 253 * :data:`SIG_BLOCK`: The set of blocked signals is the union of the current 254 set and the *mask* argument. 255 * :data:`SIG_UNBLOCK`: The signals in *mask* are removed from the current 256 set of blocked signals. It is permissible to attempt to unblock a 257 signal which is not blocked. 258 * :data:`SIG_SETMASK`: The set of blocked signals is set to the *mask* 259 argument. 260 261 *mask* is a set of signal numbers (e.g. {:const:`signal.SIGINT`, 262 :const:`signal.SIGTERM`}). Use ``range(1, signal.NSIG)`` for a full mask 263 including all signals. 264 265 For example, ``signal.pthread_sigmask(signal.SIG_BLOCK, [])`` reads the 266 signal mask of the calling thread. 267 268 Availability: Unix. See the man page :manpage:`sigprocmask(3)` and 269 :manpage:`pthread_sigmask(3)` for further information. 270 271 See also :func:`pause`, :func:`sigpending` and :func:`sigwait`. 272 273 .. versionadded:: 3.3 274 275 276 .. function:: setitimer(which, seconds[, interval]) 277 278 Sets given interval timer (one of :const:`signal.ITIMER_REAL`, 279 :const:`signal.ITIMER_VIRTUAL` or :const:`signal.ITIMER_PROF`) specified 280 by *which* to fire after *seconds* (float is accepted, different from 281 :func:`alarm`) and after that every *interval* seconds. The interval 282 timer specified by *which* can be cleared by setting seconds to zero. 283 284 When an interval timer fires, a signal is sent to the process. 285 The signal sent is dependent on the timer being used; 286 :const:`signal.ITIMER_REAL` will deliver :const:`SIGALRM`, 287 :const:`signal.ITIMER_VIRTUAL` sends :const:`SIGVTALRM`, 288 and :const:`signal.ITIMER_PROF` will deliver :const:`SIGPROF`. 289 290 The old values are returned as a tuple: (delay, interval). 291 292 Attempting to pass an invalid interval timer will cause an 293 :exc:`ItimerError`. Availability: Unix. 294 295 296 .. function:: getitimer(which) 297 298 Returns current value of a given interval timer specified by *which*. 299 Availability: Unix. 300 301 302 .. function:: set_wakeup_fd(fd) 303 304 Set the wakeup file descriptor to *fd*. When a signal is received, the 305 signal number is written as a single byte into the fd. This can be used by 306 a library to wakeup a poll or select call, allowing the signal to be fully 307 processed. 308 309 The old wakeup fd is returned. *fd* must be non-blocking. It is up to the 310 library to remove any bytes before calling poll or select again. 311 312 Use for example ``struct.unpack('%uB' % len(data), data)`` to decode the 313 signal numbers list. 314 315 When threads are enabled, this function can only be called from the main thread; 316 attempting to call it from other threads will cause a :exc:`ValueError` 317 exception to be raised. 318 319 .. versionchanged:: 3.5 320 On Windows, the function now also supports socket handles. 321 322 323 .. function:: siginterrupt(signalnum, flag) 324 325 Change system call restart behaviour: if *flag* is :const:`False`, system 326 calls will be restarted when interrupted by signal *signalnum*, otherwise 327 system calls will be interrupted. Returns nothing. Availability: Unix (see 328 the man page :manpage:`siginterrupt(3)` for further information). 329 330 Note that installing a signal handler with :func:`signal` will reset the 331 restart behaviour to interruptible by implicitly calling 332 :c:func:`siginterrupt` with a true *flag* value for the given signal. 333 334 335 .. function:: signal(signalnum, handler) 336 337 Set the handler for signal *signalnum* to the function *handler*. *handler* can 338 be a callable Python object taking two arguments (see below), or one of the 339 special values :const:`signal.SIG_IGN` or :const:`signal.SIG_DFL`. The previous 340 signal handler will be returned (see the description of :func:`getsignal` 341 above). (See the Unix man page :manpage:`signal(2)`.) 342 343 When threads are enabled, this function can only be called from the main thread; 344 attempting to call it from other threads will cause a :exc:`ValueError` 345 exception to be raised. 346 347 The *handler* is called with two arguments: the signal number and the current 348 stack frame (``None`` or a frame object; for a description of frame objects, 349 see the :ref:`description in the type hierarchy <frame-objects>` or see the 350 attribute descriptions in the :mod:`inspect` module). 351 352 On Windows, :func:`signal` can only be called with :const:`SIGABRT`, 353 :const:`SIGFPE`, :const:`SIGILL`, :const:`SIGINT`, :const:`SIGSEGV`, 354 :const:`SIGTERM`, or :const:`SIGBREAK`. 355 A :exc:`ValueError` will be raised in any other case. 356 Note that not all systems define the same set of signal names; an 357 :exc:`AttributeError` will be raised if a signal name is not defined as 358 ``SIG*`` module level constant. 359 360 361 .. function:: sigpending() 362 363 Examine the set of signals that are pending for delivery to the calling 364 thread (i.e., the signals which have been raised while blocked). Return the 365 set of the pending signals. 366 367 Availability: Unix (see the man page :manpage:`sigpending(2)` for further 368 information). 369 370 See also :func:`pause`, :func:`pthread_sigmask` and :func:`sigwait`. 371 372 .. versionadded:: 3.3 373 374 375 .. function:: sigwait(sigset) 376 377 Suspend execution of the calling thread until the delivery of one of the 378 signals specified in the signal set *sigset*. The function accepts the signal 379 (removes it from the pending list of signals), and returns the signal number. 380 381 Availability: Unix (see the man page :manpage:`sigwait(3)` for further 382 information). 383 384 See also :func:`pause`, :func:`pthread_sigmask`, :func:`sigpending`, 385 :func:`sigwaitinfo` and :func:`sigtimedwait`. 386 387 .. versionadded:: 3.3 388 389 390 .. function:: sigwaitinfo(sigset) 391 392 Suspend execution of the calling thread until the delivery of one of the 393 signals specified in the signal set *sigset*. The function accepts the 394 signal and removes it from the pending list of signals. If one of the 395 signals in *sigset* is already pending for the calling thread, the function 396 will return immediately with information about that signal. The signal 397 handler is not called for the delivered signal. The function raises an 398 :exc:`InterruptedError` if it is interrupted by a signal that is not in 399 *sigset*. 400 401 The return value is an object representing the data contained in the 402 :c:type:`siginfo_t` structure, namely: :attr:`si_signo`, :attr:`si_code`, 403 :attr:`si_errno`, :attr:`si_pid`, :attr:`si_uid`, :attr:`si_status`, 404 :attr:`si_band`. 405 406 Availability: Unix (see the man page :manpage:`sigwaitinfo(2)` for further 407 information). 408 409 See also :func:`pause`, :func:`sigwait` and :func:`sigtimedwait`. 410 411 .. versionadded:: 3.3 412 413 .. versionchanged:: 3.5 414 The function is now retried if interrupted by a signal not in *sigset* 415 and the signal handler does not raise an exception (see :pep:`475` for 416 the rationale). 417 418 419 .. function:: sigtimedwait(sigset, timeout) 420 421 Like :func:`sigwaitinfo`, but takes an additional *timeout* argument 422 specifying a timeout. If *timeout* is specified as :const:`0`, a poll is 423 performed. Returns :const:`None` if a timeout occurs. 424 425 Availability: Unix (see the man page :manpage:`sigtimedwait(2)` for further 426 information). 427 428 See also :func:`pause`, :func:`sigwait` and :func:`sigwaitinfo`. 429 430 .. versionadded:: 3.3 431 432 .. versionchanged:: 3.5 433 The function is now retried with the recomputed *timeout* if interrupted 434 by a signal not in *sigset* and the signal handler does not raise an 435 exception (see :pep:`475` for the rationale). 436 437 438 .. _signal-example: 439 440 Example 441 ------- 442 443 Here is a minimal example program. It uses the :func:`alarm` function to limit 444 the time spent waiting to open a file; this is useful if the file is for a 445 serial device that may not be turned on, which would normally cause the 446 :func:`os.open` to hang indefinitely. The solution is to set a 5-second alarm 447 before opening the file; if the operation takes too long, the alarm signal will 448 be sent, and the handler raises an exception. :: 449 450 import signal, os 451 452 def handler(signum, frame): 453 print('Signal handler called with signal', signum) 454 raise OSError("Couldn't open device!") 455 456 # Set the signal handler and a 5-second alarm 457 signal.signal(signal.SIGALRM, handler) 458 signal.alarm(5) 459 460 # This open() may hang indefinitely 461 fd = os.open('/dev/ttyS0', os.O_RDWR) 462 463 signal.alarm(0) # Disable the alarm 464 465
