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 the

    56    default function for the signal.  For example, on most systems the default

    57    action for :const:`SIGQUIT` is to dump core and exit, while the default action

    58    for :const:`SIGCLD` 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 a 

   161    :exc:`ItimerError`.

   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 

   170    .. versionadded:: 2.6

   171 

   172 

   173 .. function:: set_wakeup_fd(fd)

   174 

   175    Set the wakeup fd to *fd*.  When a signal is received, a ``'\0'`` byte is

   176    written to the fd.  This can be used by a library to wakeup a poll or select

   177    call, allowing the signal to be fully processed.

   178 

   179    The old wakeup fd is returned.  *fd* must be non-blocking.  It is up to the

   180    library to remove any bytes before calling poll or select again.

   181 

   182    When threads are enabled, this function can only be called from the main thread;

   183    attempting to call it from other threads will cause a :exc:`ValueError`

   184    exception to be raised.

   185 

   186 

   187 .. function:: siginterrupt(signalnum, flag)

   188 

   189    Change system call restart behaviour: if *flag* is :const:`False`, system calls

   190    will be restarted when interrupted by signal *signalnum*, otherwise system calls will

   191    be interrupted. Returns nothing. Availability: Unix (see the man page

   192    :manpage:`siginterrupt(3)` for further information).

   193    

   194    Note that installing a signal handler with :func:`signal` will reset the restart

   195    behaviour to interruptible by implicitly calling :cfunc:`siginterrupt` with a true *flag*

   196    value for the given signal.

   197 

   198    .. versionadded:: 2.6

   199 

   200 

   201 .. function:: signal(signalnum, handler)

   202 

   203    Set the handler for signal *signalnum* to the function *handler*.  *handler* can

   204    be a callable Python object taking two arguments (see below), or one of the

   205    special values :const:`signal.SIG_IGN` or :const:`signal.SIG_DFL`.  The previous

   206    signal handler will be returned (see the description of :func:`getsignal`

   207    above).  (See the Unix man page :manpage:`signal(2)`.)

   208 

   209    When threads are enabled, this function can only be called from the main thread;

   210    attempting to call it from other threads will cause a :exc:`ValueError`

   211    exception to be raised.

   212 

   213    The *handler* is called with two arguments: the signal number and the current

   214    stack frame (``None`` or a frame object; for a description of frame objects, see

   215    the reference manual section on the standard type hierarchy or see the attribute

   216    descriptions in the :mod:`inspect` module).

   217 

   218 

   219 .. _signal-example:

   220 

   221 Example

   222 -------

   223 

   224 Here is a minimal example program. It uses the :func:`alarm` function to limit

   225 the time spent waiting to open a file; this is useful if the file is for a

   226 serial device that may not be turned on, which would normally cause the

   227 :func:`os.open` to hang indefinitely.  The solution is to set a 5-second alarm

   228 before opening the file; if the operation takes too long, the alarm signal will

   229 be sent, and the handler raises an exception. ::

   230 

   231    import signal, os

   232 

   233    def handler(signum, frame):

   234        print 'Signal handler called with signal', signum

   235        raise IOError, "Couldn't open device!"

   236 

   237    # Set the signal handler and a 5-second alarm

   238    signal.signal(signal.SIGALRM, handler)

   239    signal.alarm(5)

   240 

   241    # This open() may hang indefinitely

   242    fd = os.open('/dev/ttyS0', os.O_RDWR)  

   243 

   244    signal.alarm(0)          # Disable the alarm

   245