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