Doc/library/signal.rst

   1
   2 :mod:`signal` --- Set handlers for asynchronous events
   3 ======================================================
   4
   5 .. module:: signal
   6    :synopsis: Set handlers for asynchronous events.
   7
   8
   9 This module provides mechanisms to use signal handlers in Python. Some general
  10 rules for working with signals and their handlers:
  11
  12 * A handler for a particular signal, once set, remains installed until it is
  13   explicitly reset (Python emulates the BSD style interface regardless of the
  14   underlying implementation), with the exception of the handler for
  15   :const:`SIGCHLD`, which follows the underlying implementation.
  16
  17 * There is no way to "block" signals temporarily from critical sections (since
  18   this is not supported by all Unix flavors).
  19
  20 * Although Python signal handlers are called asynchronously as far as the Python
  21   user is concerned, they can only occur between the "atomic" instructions of the
  22   Python interpreter.  This means that signals arriving during long calculations
  23   implemented purely in C (such as regular expression matches on large bodies of
  24   text) may be delayed for an arbitrary amount of time.
  25
  26 * When a signal arrives during an I/O operation, it is possible that the I/O
  27   operation raises an exception after the signal handler returns. This is
  28   dependent on the underlying Unix system's semantics regarding interrupted system
  29   calls.
  30
  31 * Because the C signal handler always returns, it makes little sense to catch
  32   synchronous errors like :const:`SIGFPE` or :const:`SIGSEGV`.
  33
  34 * Python installs a small number of signal handlers by default: :const:`SIGPIPE`
  35   is ignored (so write errors on pipes and sockets can be reported as ordinary
  36   Python exceptions) and :const:`SIGINT` is translated into a
  37   :exc:`KeyboardInterrupt` exception.  All of these can be overridden.
  38
  39 * Some care must be taken if both signals and threads are used in the same
  40   program.  The fundamental thing to remember in using signals and threads
  41   simultaneously is: always perform :func:`signal` operations in the main thread
  42   of execution.  Any thread can perform an :func:`alarm`, :func:`getsignal`,
  43   :func:`pause`, :func:`setitimer` or :func:`getitimer`; only the main thread
  44   can set a new signal handler, and the main thread will be the only one to
  45   receive signals (this is enforced by the Python :mod:`signal` module, even
  46   if the underlying thread implementation supports sending signals to
  47   individual threads).  This means that signals can't be used as a means of
  48   inter-thread communication.  Use locks instead.
  49
  50 The variables defined in the :mod:`signal` module are:
  51
  52
  53 .. data:: SIG_DFL
  54
  55    This is one of two standard signal handling options; it will simply perform
  56    the default function for the signal.  For example, on most systems the
  57    default action for :const:`SIGQUIT` is to dump core and exit, while the
  58    default action for :const:`SIGCHLD` is to simply ignore it.
  59
  60
  61 .. data:: SIG_IGN
  62
  63    This is another standard signal handler, which will simply ignore the given
  64    signal.
  65
  66
  67 .. data:: SIG*
  68
  69    All the signal numbers are defined symbolically.  For example, the hangup signal
  70    is defined as :const:`signal.SIGHUP`; the variable names are identical to the
  71    names used in C programs, as found in ``<signal.h>``. The Unix man page for
  72    ':cfunc:`signal`' lists the existing signals (on some systems this is
  73    :manpage:`signal(2)`, on others the list is in :manpage:`signal(7)`). Note that
  74    not all systems define the same set of signal names; only those names defined by
  75    the system are defined by this module.
  76
  77
  78 .. data:: NSIG
  79
  80    One more than the number of the highest signal number.
  81
  82
  83 .. data:: ITIMER_REAL
  84
  85    Decrements interval timer in real time, and delivers :const:`SIGALRM` upon expiration.
  86
  87
  88 .. data:: ITIMER_VIRTUAL
  89
  90    Decrements interval timer only when the process is executing, and delivers
  91    SIGVTALRM upon expiration.
  92
  93
  94 .. data:: ITIMER_PROF
  95
  96    Decrements interval timer both when the process executes and when the
  97    system is executing on behalf of the process. Coupled with ITIMER_VIRTUAL,
  98    this timer is usually used to profile the time spent by the application
  99    in user and kernel space. SIGPROF is delivered upon expiration.
 100
 101
 102 The :mod:`signal` module defines one exception:
 103
 104 .. exception:: ItimerError
 105
 106    Raised to signal an error from the underlying :func:`setitimer` or
 107    :func:`getitimer` implementation. Expect this error if an invalid
 108    interval timer or a negative time is passed to :func:`setitimer`.
 109    This error is a subtype of :exc:`IOError`.
 110
 111
 112 The :mod:`signal` module defines the following functions:
 113
 114
 115 .. function:: alarm(time)
 116
 117    If *time* is non-zero, this function requests that a :const:`SIGALRM` signal be
 118    sent to the process in *time* seconds. Any previously scheduled alarm is
 119    canceled (only one alarm can be scheduled at any time).  The returned value is
 120    then the number of seconds before any previously set alarm was to have been
 121    delivered. If *time* is zero, no alarm is scheduled, and any scheduled alarm is
 122    canceled.  If the return value is zero, no alarm is currently scheduled.  (See
 123    the Unix man page :manpage:`alarm(2)`.) Availability: Unix.
 124
 125
 126 .. function:: getsignal(signalnum)
 127
 128    Return the current signal handler for the signal *signalnum*. The returned value
 129    may be a callable Python object, or one of the special values
 130    :const:`signal.SIG_IGN`, :const:`signal.SIG_DFL` or :const:`None`.  Here,
 131    :const:`signal.SIG_IGN` means that the signal was previously ignored,
 132    :const:`signal.SIG_DFL` means that the default way of handling the signal was
 133    previously in use, and ``None`` means that the previous signal handler was not
 134    installed from Python.
 135
 136
 137 .. function:: pause()
 138
 139    Cause the process to sleep until a signal is received; the appropriate handler
 140    will then be called.  Returns nothing.  Not on Windows. (See the Unix man page
 141    :manpage:`signal(2)`.)
 142
 143
 144 .. function:: setitimer(which, seconds[, interval])
 145
 146    Sets given interval timer (one of :const:`signal.ITIMER_REAL`,
 147    :const:`signal.ITIMER_VIRTUAL` or :const:`signal.ITIMER_PROF`) specified
 148    by *which* to fire after *seconds* (float is accepted, different from
 149    :func:`alarm`) and after that every *interval* seconds. The interval
 150    timer specified by *which* can be cleared by setting seconds to zero.
 151
 152    When an interval timer fires, a signal is sent to the process.
 153    The signal sent is dependent on the timer being used;
 154    :const:`signal.ITIMER_REAL` will deliver :const:`SIGALRM`,
 155    :const:`signal.ITIMER_VIRTUAL` sends :const:`SIGVTALRM`,
 156    and :const:`signal.ITIMER_PROF` will deliver :const:`SIGPROF`.
 157
 158    The old values are returned as a tuple: (delay, interval).
 159
 160    Attempting to pass an invalid interval timer will cause an
 161    :exc:`ItimerError`.  Availability: Unix.
 162
 163    .. versionadded:: 2.6
 164
 165
 166 .. function:: getitimer(which)
 167
 168    Returns current value of a given interval timer specified by *which*.
 169    Availability: Unix.
 170
 171    .. versionadded:: 2.6
 172
 173
 174 .. function:: set_wakeup_fd(fd)
 175
 176    Set the wakeup fd to *fd*.  When a signal is received, a ``'\0'`` byte is
 177    written to the fd.  This can be used by a library to wakeup a poll or select
 178    call, allowing the signal to be fully processed.
 179
 180    The old wakeup fd is returned.  *fd* must be non-blocking.  It is up to the
 181    library to remove any bytes before calling poll or select again.
 182
 183    When threads are enabled, this function can only be called from the main thread;
 184    attempting to call it from other threads will cause a :exc:`ValueError`
 185    exception to be raised.
 186
 187
 188 .. function:: siginterrupt(signalnum, flag)
 189
 190    Change system call restart behaviour: if *flag* is :const:`False`, system
 191    calls will be restarted when interrupted by signal *signalnum*, otherwise
 192    system calls will be interrupted.  Returns nothing.  Availability: Unix (see
 193    the man page :manpage:`siginterrupt(3)` for further information).
 194
 195    Note that installing a signal handler with :func:`signal` will reset the
 196    restart behaviour to interruptible by implicitly calling
 197    :cfunc:`siginterrupt` with a true *flag* value for the given signal.
 198
 199    .. versionadded:: 2.6
 200
 201
 202 .. function:: signal(signalnum, handler)
 203
 204    Set the handler for signal *signalnum* to the function *handler*.  *handler* can
 205    be a callable Python object taking two arguments (see below), or one of the
 206    special values :const:`signal.SIG_IGN` or :const:`signal.SIG_DFL`.  The previous
 207    signal handler will be returned (see the description of :func:`getsignal`
 208    above).  (See the Unix man page :manpage:`signal(2)`.)
 209
 210    When threads are enabled, this function can only be called from the main thread;
 211    attempting to call it from other threads will cause a :exc:`ValueError`
 212    exception to be raised.
 213
 214    The *handler* is called with two arguments: the signal number and the current
 215    stack frame (``None`` or a frame object; for a description of frame objects,
 216    see the :ref:`description in the type hierarchy <frame-objects>` or see the
 217    attribute descriptions in the :mod:`inspect` module).
 218
 219
 220 .. _signal-example:
 221
 222 Example
 223 -------
 224
 225 Here is a minimal example program. It uses the :func:`alarm` function to limit
 226 the time spent waiting to open a file; this is useful if the file is for a
 227 serial device that may not be turned on, which would normally cause the
 228 :func:`os.open` to hang indefinitely.  The solution is to set a 5-second alarm
 229 before opening the file; if the operation takes too long, the alarm signal will
 230 be sent, and the handler raises an exception. ::
 231
 232    import signal, os
 233
 234    def handler(signum, frame):
 235        print 'Signal handler called with signal', signum
 236        raise IOError("Couldn't open device!")
 237
 238    # Set the signal handler and a 5-second alarm
 239    signal.signal(signal.SIGALRM, handler)
 240    signal.alarm(5)
 241
 242    # This open() may hang indefinitely
 243    fd = os.open('/dev/ttyS0', os.O_RDWR)
 244
 245    signal.alarm(0)          # Disable the alarm
 246