• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1:mod:`signal` --- Set handlers for asynchronous events
2======================================================
3
4.. module:: signal
5   :synopsis: Set handlers for asynchronous events.
6
7--------------
8
9This module provides mechanisms to use signal handlers in Python.
10
11
12General rules
13-------------
14
15The :func:`signal.signal` function allows defining custom handlers to be
16executed when a signal is received.  A small number of default handlers are
17installed: :const:`SIGPIPE` is ignored (so write errors on pipes and sockets
18can be reported as ordinary Python exceptions) and :const:`SIGINT` is
19translated into a :exc:`KeyboardInterrupt` exception.
20
21A handler for a particular signal, once set, remains installed until it is
22explicitly reset (Python emulates the BSD style interface regardless of the
23underlying implementation), with the exception of the handler for
24:const:`SIGCHLD`, which follows the underlying implementation.
25
26
27Execution of Python signal handlers
28^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
29
30A Python signal handler does not get executed inside the low-level (C) signal
31handler.  Instead, the low-level signal handler sets a flag which tells the
32:term:`virtual machine` to execute the corresponding Python signal handler
33at a later point(for example at the next :term:`bytecode` instruction).
34This 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
52Signals and threads
53^^^^^^^^^^^^^^^^^^^
54
55Python signal handlers are always executed in the main Python thread,
56even if the signal was received in another thread.  This means that signals
57can't be used as a means of inter-thread communication.  You can use
58the synchronization primitives from the :mod:`threading` module instead.
59
60Besides, only the main thread is allowed to set a new signal handler.
61
62
63Module 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
76The 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
171The :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
185The :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
440Example
441-------
442
443Here is a minimal example program. It uses the :func:`alarm` function to limit
444the time spent waiting to open a file; this is useful if the file is for a
445serial 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
447before opening the file; if the operation takes too long, the alarm signal will
448be 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