704 lines
61 KiB
HTML
704 lines
61 KiB
HTML
|
||
<!DOCTYPE html>
|
||
|
||
<html xmlns="http://www.w3.org/1999/xhtml">
|
||
<head>
|
||
<meta charset="utf-8" />
|
||
<title>signal — Set handlers for asynchronous events — Python 3.7.4 documentation</title>
|
||
<link rel="stylesheet" href="../_static/pydoctheme.css" type="text/css" />
|
||
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
|
||
|
||
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
|
||
<script type="text/javascript" src="../_static/jquery.js"></script>
|
||
<script type="text/javascript" src="../_static/underscore.js"></script>
|
||
<script type="text/javascript" src="../_static/doctools.js"></script>
|
||
<script type="text/javascript" src="../_static/language_data.js"></script>
|
||
|
||
<script type="text/javascript" src="../_static/sidebar.js"></script>
|
||
|
||
<link rel="search" type="application/opensearchdescription+xml"
|
||
title="Search within Python 3.7.4 documentation"
|
||
href="../_static/opensearch.xml"/>
|
||
<link rel="author" title="About these documents" href="../about.html" />
|
||
<link rel="index" title="Index" href="../genindex.html" />
|
||
<link rel="search" title="Search" href="../search.html" />
|
||
<link rel="copyright" title="Copyright" href="../copyright.html" />
|
||
<link rel="next" title="mmap — Memory-mapped file support" href="mmap.html" />
|
||
<link rel="prev" title="asynchat — Asynchronous socket command/response handler" href="asynchat.html" />
|
||
<link rel="shortcut icon" type="image/png" href="../_static/py.png" />
|
||
<link rel="canonical" href="https://docs.python.org/3/library/signal.html" />
|
||
|
||
<script type="text/javascript" src="../_static/copybutton.js"></script>
|
||
<script type="text/javascript" src="../_static/switchers.js"></script>
|
||
|
||
|
||
|
||
<style>
|
||
@media only screen {
|
||
table.full-width-table {
|
||
width: 100%;
|
||
}
|
||
}
|
||
</style>
|
||
|
||
|
||
</head><body>
|
||
|
||
<div class="related" role="navigation" aria-label="related navigation">
|
||
<h3>Navigation</h3>
|
||
<ul>
|
||
<li class="right" style="margin-right: 10px">
|
||
<a href="../genindex.html" title="General Index"
|
||
accesskey="I">index</a></li>
|
||
<li class="right" >
|
||
<a href="../py-modindex.html" title="Python Module Index"
|
||
>modules</a> |</li>
|
||
<li class="right" >
|
||
<a href="mmap.html" title="mmap — Memory-mapped file support"
|
||
accesskey="N">next</a> |</li>
|
||
<li class="right" >
|
||
<a href="asynchat.html" title="asynchat — Asynchronous socket command/response handler"
|
||
accesskey="P">previous</a> |</li>
|
||
<li><img src="../_static/py.png" alt=""
|
||
style="vertical-align: middle; margin-top: -1px"/></li>
|
||
<li><a href="https://www.python.org/">Python</a> »</li>
|
||
<li>
|
||
<span class="language_switcher_placeholder">en</span>
|
||
<span class="version_switcher_placeholder">3.7.4</span>
|
||
<a href="../index.html">Documentation </a> »
|
||
</li>
|
||
|
||
<li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> »</li>
|
||
<li class="nav-item nav-item-2"><a href="ipc.html" accesskey="U">Networking and Interprocess Communication</a> »</li>
|
||
<li class="right">
|
||
|
||
|
||
<div class="inline-search" style="display: none" role="search">
|
||
<form class="inline-search" action="../search.html" method="get">
|
||
<input placeholder="Quick search" type="text" name="q" />
|
||
<input type="submit" value="Go" />
|
||
<input type="hidden" name="check_keywords" value="yes" />
|
||
<input type="hidden" name="area" value="default" />
|
||
</form>
|
||
</div>
|
||
<script type="text/javascript">$('.inline-search').show(0);</script>
|
||
|
|
||
</li>
|
||
|
||
</ul>
|
||
</div>
|
||
|
||
<div class="document">
|
||
<div class="documentwrapper">
|
||
<div class="bodywrapper">
|
||
<div class="body" role="main">
|
||
|
||
<div class="section" id="module-signal">
|
||
<span id="signal-set-handlers-for-asynchronous-events"></span><h1><a class="reference internal" href="#module-signal" title="signal: Set handlers for asynchronous events."><code class="xref py py-mod docutils literal notranslate"><span class="pre">signal</span></code></a> — Set handlers for asynchronous events<a class="headerlink" href="#module-signal" title="Permalink to this headline">¶</a></h1>
|
||
<hr class="docutils" />
|
||
<p>This module provides mechanisms to use signal handlers in Python.</p>
|
||
<div class="section" id="general-rules">
|
||
<h2>General rules<a class="headerlink" href="#general-rules" title="Permalink to this headline">¶</a></h2>
|
||
<p>The <a class="reference internal" href="#signal.signal" title="signal.signal"><code class="xref py py-func docutils literal notranslate"><span class="pre">signal.signal()</span></code></a> function allows defining custom handlers to be
|
||
executed when a signal is received. A small number of default handlers are
|
||
installed: <code class="xref py py-const docutils literal notranslate"><span class="pre">SIGPIPE</span></code> is ignored (so write errors on pipes and sockets
|
||
can be reported as ordinary Python exceptions) and <code class="xref py py-const docutils literal notranslate"><span class="pre">SIGINT</span></code> is
|
||
translated into a <a class="reference internal" href="exceptions.html#KeyboardInterrupt" title="KeyboardInterrupt"><code class="xref py py-exc docutils literal notranslate"><span class="pre">KeyboardInterrupt</span></code></a> exception if the parent process
|
||
has not changed it.</p>
|
||
<p>A handler for a particular signal, once set, remains installed until it is
|
||
explicitly reset (Python emulates the BSD style interface regardless of the
|
||
underlying implementation), with the exception of the handler for
|
||
<code class="xref py py-const docutils literal notranslate"><span class="pre">SIGCHLD</span></code>, which follows the underlying implementation.</p>
|
||
<div class="section" id="execution-of-python-signal-handlers">
|
||
<h3>Execution of Python signal handlers<a class="headerlink" href="#execution-of-python-signal-handlers" title="Permalink to this headline">¶</a></h3>
|
||
<p>A Python signal handler does not get executed inside the low-level (C) signal
|
||
handler. Instead, the low-level signal handler sets a flag which tells the
|
||
<a class="reference internal" href="../glossary.html#term-virtual-machine"><span class="xref std std-term">virtual machine</span></a> to execute the corresponding Python signal handler
|
||
at a later point(for example at the next <a class="reference internal" href="../glossary.html#term-bytecode"><span class="xref std std-term">bytecode</span></a> instruction).
|
||
This has consequences:</p>
|
||
<ul class="simple">
|
||
<li><p>It makes little sense to catch synchronous errors like <code class="xref py py-const docutils literal notranslate"><span class="pre">SIGFPE</span></code> or
|
||
<code class="xref py py-const docutils literal notranslate"><span class="pre">SIGSEGV</span></code> that are caused by an invalid operation in C code. Python
|
||
will return from the signal handler to the C code, which is likely to raise
|
||
the same signal again, causing Python to apparently hang. From Python 3.3
|
||
onwards, you can use the <a class="reference internal" href="faulthandler.html#module-faulthandler" title="faulthandler: Dump the Python traceback."><code class="xref py py-mod docutils literal notranslate"><span class="pre">faulthandler</span></code></a> module to report on synchronous
|
||
errors.</p></li>
|
||
<li><p>A long-running calculation implemented purely in C (such as regular
|
||
expression matching on a large body of text) may run uninterrupted for an
|
||
arbitrary amount of time, regardless of any signals received. The Python
|
||
signal handlers will be called when the calculation finishes.</p></li>
|
||
</ul>
|
||
</div>
|
||
<div class="section" id="signals-and-threads">
|
||
<span id="id1"></span><h3>Signals and threads<a class="headerlink" href="#signals-and-threads" title="Permalink to this headline">¶</a></h3>
|
||
<p>Python signal handlers are always executed in the main Python thread,
|
||
even if the signal was received in another thread. This means that signals
|
||
can’t be used as a means of inter-thread communication. You can use
|
||
the synchronization primitives from the <a class="reference internal" href="threading.html#module-threading" title="threading: Thread-based parallelism."><code class="xref py py-mod docutils literal notranslate"><span class="pre">threading</span></code></a> module instead.</p>
|
||
<p>Besides, only the main thread is allowed to set a new signal handler.</p>
|
||
</div>
|
||
</div>
|
||
<div class="section" id="module-contents">
|
||
<h2>Module contents<a class="headerlink" href="#module-contents" title="Permalink to this headline">¶</a></h2>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.5: </span>signal (SIG*), handler (<a class="reference internal" href="#signal.SIG_DFL" title="signal.SIG_DFL"><code class="xref py py-const docutils literal notranslate"><span class="pre">SIG_DFL</span></code></a>, <a class="reference internal" href="#signal.SIG_IGN" title="signal.SIG_IGN"><code class="xref py py-const docutils literal notranslate"><span class="pre">SIG_IGN</span></code></a>) and sigmask
|
||
(<a class="reference internal" href="#signal.SIG_BLOCK" title="signal.SIG_BLOCK"><code class="xref py py-const docutils literal notranslate"><span class="pre">SIG_BLOCK</span></code></a>, <a class="reference internal" href="#signal.SIG_UNBLOCK" title="signal.SIG_UNBLOCK"><code class="xref py py-const docutils literal notranslate"><span class="pre">SIG_UNBLOCK</span></code></a>, <a class="reference internal" href="#signal.SIG_SETMASK" title="signal.SIG_SETMASK"><code class="xref py py-const docutils literal notranslate"><span class="pre">SIG_SETMASK</span></code></a>)
|
||
related constants listed below were turned into
|
||
<a class="reference internal" href="enum.html#enum.IntEnum" title="enum.IntEnum"><code class="xref py py-class docutils literal notranslate"><span class="pre">enums</span></code></a>.
|
||
<a class="reference internal" href="#signal.getsignal" title="signal.getsignal"><code class="xref py py-func docutils literal notranslate"><span class="pre">getsignal()</span></code></a>, <a class="reference internal" href="#signal.pthread_sigmask" title="signal.pthread_sigmask"><code class="xref py py-func docutils literal notranslate"><span class="pre">pthread_sigmask()</span></code></a>, <a class="reference internal" href="#signal.sigpending" title="signal.sigpending"><code class="xref py py-func docutils literal notranslate"><span class="pre">sigpending()</span></code></a> and
|
||
<a class="reference internal" href="#signal.sigwait" title="signal.sigwait"><code class="xref py py-func docutils literal notranslate"><span class="pre">sigwait()</span></code></a> functions return human-readable
|
||
<a class="reference internal" href="enum.html#enum.IntEnum" title="enum.IntEnum"><code class="xref py py-class docutils literal notranslate"><span class="pre">enums</span></code></a>.</p>
|
||
</div>
|
||
<p>The variables defined in the <a class="reference internal" href="#module-signal" title="signal: Set handlers for asynchronous events."><code class="xref py py-mod docutils literal notranslate"><span class="pre">signal</span></code></a> module are:</p>
|
||
<dl class="data">
|
||
<dt id="signal.SIG_DFL">
|
||
<code class="descclassname">signal.</code><code class="descname">SIG_DFL</code><a class="headerlink" href="#signal.SIG_DFL" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>This is one of two standard signal handling options; it will simply perform
|
||
the default function for the signal. For example, on most systems the
|
||
default action for <code class="xref py py-const docutils literal notranslate"><span class="pre">SIGQUIT</span></code> is to dump core and exit, while the
|
||
default action for <code class="xref py py-const docutils literal notranslate"><span class="pre">SIGCHLD</span></code> is to simply ignore it.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="data">
|
||
<dt id="signal.SIG_IGN">
|
||
<code class="descclassname">signal.</code><code class="descname">SIG_IGN</code><a class="headerlink" href="#signal.SIG_IGN" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>This is another standard signal handler, which will simply ignore the given
|
||
signal.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="data">
|
||
<dt>
|
||
<code class="descname">SIG*</code></dt>
|
||
<dd><p>All the signal numbers are defined symbolically. For example, the hangup signal
|
||
is defined as <code class="xref py py-const docutils literal notranslate"><span class="pre">signal.SIGHUP</span></code>; the variable names are identical to the
|
||
names used in C programs, as found in <code class="docutils literal notranslate"><span class="pre"><signal.h></span></code>. The Unix man page for
|
||
‘<code class="xref c c-func docutils literal notranslate"><span class="pre">signal()</span></code>’ lists the existing signals (on some systems this is
|
||
<em class="manpage">signal(2)</em>, on others the list is in <em class="manpage">signal(7)</em>). Note that
|
||
not all systems define the same set of signal names; only those names defined by
|
||
the system are defined by this module.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="data">
|
||
<dt id="signal.CTRL_C_EVENT">
|
||
<code class="descclassname">signal.</code><code class="descname">CTRL_C_EVENT</code><a class="headerlink" href="#signal.CTRL_C_EVENT" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>The signal corresponding to the <kbd class="kbd docutils literal notranslate">Ctrl+C</kbd> keystroke event. This signal can
|
||
only be used with <a class="reference internal" href="os.html#os.kill" title="os.kill"><code class="xref py py-func docutils literal notranslate"><span class="pre">os.kill()</span></code></a>.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Windows.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.2.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="data">
|
||
<dt id="signal.CTRL_BREAK_EVENT">
|
||
<code class="descclassname">signal.</code><code class="descname">CTRL_BREAK_EVENT</code><a class="headerlink" href="#signal.CTRL_BREAK_EVENT" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>The signal corresponding to the <kbd class="kbd docutils literal notranslate">Ctrl+Break</kbd> keystroke event. This signal can
|
||
only be used with <a class="reference internal" href="os.html#os.kill" title="os.kill"><code class="xref py py-func docutils literal notranslate"><span class="pre">os.kill()</span></code></a>.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Windows.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.2.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="data">
|
||
<dt id="signal.NSIG">
|
||
<code class="descclassname">signal.</code><code class="descname">NSIG</code><a class="headerlink" href="#signal.NSIG" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>One more than the number of the highest signal number.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="data">
|
||
<dt id="signal.ITIMER_REAL">
|
||
<code class="descclassname">signal.</code><code class="descname">ITIMER_REAL</code><a class="headerlink" href="#signal.ITIMER_REAL" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Decrements interval timer in real time, and delivers <code class="xref py py-const docutils literal notranslate"><span class="pre">SIGALRM</span></code> upon
|
||
expiration.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="data">
|
||
<dt id="signal.ITIMER_VIRTUAL">
|
||
<code class="descclassname">signal.</code><code class="descname">ITIMER_VIRTUAL</code><a class="headerlink" href="#signal.ITIMER_VIRTUAL" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Decrements interval timer only when the process is executing, and delivers
|
||
SIGVTALRM upon expiration.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="data">
|
||
<dt id="signal.ITIMER_PROF">
|
||
<code class="descclassname">signal.</code><code class="descname">ITIMER_PROF</code><a class="headerlink" href="#signal.ITIMER_PROF" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Decrements interval timer both when the process executes and when the
|
||
system is executing on behalf of the process. Coupled with ITIMER_VIRTUAL,
|
||
this timer is usually used to profile the time spent by the application
|
||
in user and kernel space. SIGPROF is delivered upon expiration.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="data">
|
||
<dt id="signal.SIG_BLOCK">
|
||
<code class="descclassname">signal.</code><code class="descname">SIG_BLOCK</code><a class="headerlink" href="#signal.SIG_BLOCK" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>A possible value for the <em>how</em> parameter to <a class="reference internal" href="#signal.pthread_sigmask" title="signal.pthread_sigmask"><code class="xref py py-func docutils literal notranslate"><span class="pre">pthread_sigmask()</span></code></a>
|
||
indicating that signals are to be blocked.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.3.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="data">
|
||
<dt id="signal.SIG_UNBLOCK">
|
||
<code class="descclassname">signal.</code><code class="descname">SIG_UNBLOCK</code><a class="headerlink" href="#signal.SIG_UNBLOCK" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>A possible value for the <em>how</em> parameter to <a class="reference internal" href="#signal.pthread_sigmask" title="signal.pthread_sigmask"><code class="xref py py-func docutils literal notranslate"><span class="pre">pthread_sigmask()</span></code></a>
|
||
indicating that signals are to be unblocked.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.3.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="data">
|
||
<dt id="signal.SIG_SETMASK">
|
||
<code class="descclassname">signal.</code><code class="descname">SIG_SETMASK</code><a class="headerlink" href="#signal.SIG_SETMASK" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>A possible value for the <em>how</em> parameter to <a class="reference internal" href="#signal.pthread_sigmask" title="signal.pthread_sigmask"><code class="xref py py-func docutils literal notranslate"><span class="pre">pthread_sigmask()</span></code></a>
|
||
indicating that the signal mask is to be replaced.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.3.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<p>The <a class="reference internal" href="#module-signal" title="signal: Set handlers for asynchronous events."><code class="xref py py-mod docutils literal notranslate"><span class="pre">signal</span></code></a> module defines one exception:</p>
|
||
<dl class="exception">
|
||
<dt id="signal.ItimerError">
|
||
<em class="property">exception </em><code class="descclassname">signal.</code><code class="descname">ItimerError</code><a class="headerlink" href="#signal.ItimerError" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Raised to signal an error from the underlying <a class="reference internal" href="#signal.setitimer" title="signal.setitimer"><code class="xref py py-func docutils literal notranslate"><span class="pre">setitimer()</span></code></a> or
|
||
<a class="reference internal" href="#signal.getitimer" title="signal.getitimer"><code class="xref py py-func docutils literal notranslate"><span class="pre">getitimer()</span></code></a> implementation. Expect this error if an invalid
|
||
interval timer or a negative time is passed to <a class="reference internal" href="#signal.setitimer" title="signal.setitimer"><code class="xref py py-func docutils literal notranslate"><span class="pre">setitimer()</span></code></a>.
|
||
This error is a subtype of <a class="reference internal" href="exceptions.html#OSError" title="OSError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">OSError</span></code></a>.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.3: </span>This error used to be a subtype of <a class="reference internal" href="exceptions.html#IOError" title="IOError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">IOError</span></code></a>, which is now an
|
||
alias of <a class="reference internal" href="exceptions.html#OSError" title="OSError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">OSError</span></code></a>.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<p>The <a class="reference internal" href="#module-signal" title="signal: Set handlers for asynchronous events."><code class="xref py py-mod docutils literal notranslate"><span class="pre">signal</span></code></a> module defines the following functions:</p>
|
||
<dl class="function">
|
||
<dt id="signal.alarm">
|
||
<code class="descclassname">signal.</code><code class="descname">alarm</code><span class="sig-paren">(</span><em>time</em><span class="sig-paren">)</span><a class="headerlink" href="#signal.alarm" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>If <em>time</em> is non-zero, this function requests that a <code class="xref py py-const docutils literal notranslate"><span class="pre">SIGALRM</span></code> signal be
|
||
sent to the process in <em>time</em> seconds. Any previously scheduled alarm is
|
||
canceled (only one alarm can be scheduled at any time). The returned value is
|
||
then the number of seconds before any previously set alarm was to have been
|
||
delivered. If <em>time</em> is zero, no alarm is scheduled, and any scheduled alarm is
|
||
canceled. If the return value is zero, no alarm is currently scheduled. (See
|
||
the Unix man page <em class="manpage">alarm(2)</em>.)</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="signal.getsignal">
|
||
<code class="descclassname">signal.</code><code class="descname">getsignal</code><span class="sig-paren">(</span><em>signalnum</em><span class="sig-paren">)</span><a class="headerlink" href="#signal.getsignal" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return the current signal handler for the signal <em>signalnum</em>. The returned value
|
||
may be a callable Python object, or one of the special values
|
||
<a class="reference internal" href="#signal.SIG_IGN" title="signal.SIG_IGN"><code class="xref py py-const docutils literal notranslate"><span class="pre">signal.SIG_IGN</span></code></a>, <a class="reference internal" href="#signal.SIG_DFL" title="signal.SIG_DFL"><code class="xref py py-const docutils literal notranslate"><span class="pre">signal.SIG_DFL</span></code></a> or <a class="reference internal" href="constants.html#None" title="None"><code class="xref py py-const docutils literal notranslate"><span class="pre">None</span></code></a>. Here,
|
||
<a class="reference internal" href="#signal.SIG_IGN" title="signal.SIG_IGN"><code class="xref py py-const docutils literal notranslate"><span class="pre">signal.SIG_IGN</span></code></a> means that the signal was previously ignored,
|
||
<a class="reference internal" href="#signal.SIG_DFL" title="signal.SIG_DFL"><code class="xref py py-const docutils literal notranslate"><span class="pre">signal.SIG_DFL</span></code></a> means that the default way of handling the signal was
|
||
previously in use, and <code class="docutils literal notranslate"><span class="pre">None</span></code> means that the previous signal handler was not
|
||
installed from Python.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="signal.pause">
|
||
<code class="descclassname">signal.</code><code class="descname">pause</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#signal.pause" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Cause the process to sleep until a signal is received; the appropriate handler
|
||
will then be called. Returns nothing. Not on Windows. (See the Unix man page
|
||
<em class="manpage">signal(2)</em>.)</p>
|
||
<p>See also <a class="reference internal" href="#signal.sigwait" title="signal.sigwait"><code class="xref py py-func docutils literal notranslate"><span class="pre">sigwait()</span></code></a>, <a class="reference internal" href="#signal.sigwaitinfo" title="signal.sigwaitinfo"><code class="xref py py-func docutils literal notranslate"><span class="pre">sigwaitinfo()</span></code></a>, <a class="reference internal" href="#signal.sigtimedwait" title="signal.sigtimedwait"><code class="xref py py-func docutils literal notranslate"><span class="pre">sigtimedwait()</span></code></a> and
|
||
<a class="reference internal" href="#signal.sigpending" title="signal.sigpending"><code class="xref py py-func docutils literal notranslate"><span class="pre">sigpending()</span></code></a>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="signal.pthread_kill">
|
||
<code class="descclassname">signal.</code><code class="descname">pthread_kill</code><span class="sig-paren">(</span><em>thread_id</em>, <em>signalnum</em><span class="sig-paren">)</span><a class="headerlink" href="#signal.pthread_kill" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Send the signal <em>signalnum</em> to the thread <em>thread_id</em>, another thread in the
|
||
same process as the caller. The target thread can be executing any code
|
||
(Python or not). However, if the target thread is executing the Python
|
||
interpreter, the Python signal handlers will be <a class="reference internal" href="#signals-and-threads"><span class="std std-ref">executed by the main
|
||
thread</span></a>. Therefore, the only point of sending a
|
||
signal to a particular Python thread would be to force a running system call
|
||
to fail with <a class="reference internal" href="exceptions.html#InterruptedError" title="InterruptedError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">InterruptedError</span></code></a>.</p>
|
||
<p>Use <a class="reference internal" href="threading.html#threading.get_ident" title="threading.get_ident"><code class="xref py py-func docutils literal notranslate"><span class="pre">threading.get_ident()</span></code></a> or the <a class="reference internal" href="threading.html#threading.Thread.ident" title="threading.Thread.ident"><code class="xref py py-attr docutils literal notranslate"><span class="pre">ident</span></code></a>
|
||
attribute of <a class="reference internal" href="threading.html#threading.Thread" title="threading.Thread"><code class="xref py py-class docutils literal notranslate"><span class="pre">threading.Thread</span></code></a> objects to get a suitable value
|
||
for <em>thread_id</em>.</p>
|
||
<p>If <em>signalnum</em> is 0, then no signal is sent, but error checking is still
|
||
performed; this can be used to check if the target thread is still running.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix (see the man page <em class="manpage">pthread_kill(3)</em> for further
|
||
information).</p>
|
||
<p>See also <a class="reference internal" href="os.html#os.kill" title="os.kill"><code class="xref py py-func docutils literal notranslate"><span class="pre">os.kill()</span></code></a>.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.3.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="signal.pthread_sigmask">
|
||
<code class="descclassname">signal.</code><code class="descname">pthread_sigmask</code><span class="sig-paren">(</span><em>how</em>, <em>mask</em><span class="sig-paren">)</span><a class="headerlink" href="#signal.pthread_sigmask" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Fetch and/or change the signal mask of the calling thread. The signal mask
|
||
is the set of signals whose delivery is currently blocked for the caller.
|
||
Return the old signal mask as a set of signals.</p>
|
||
<p>The behavior of the call is dependent on the value of <em>how</em>, as follows.</p>
|
||
<ul class="simple">
|
||
<li><p><a class="reference internal" href="#signal.SIG_BLOCK" title="signal.SIG_BLOCK"><code class="xref py py-data docutils literal notranslate"><span class="pre">SIG_BLOCK</span></code></a>: The set of blocked signals is the union of the current
|
||
set and the <em>mask</em> argument.</p></li>
|
||
<li><p><a class="reference internal" href="#signal.SIG_UNBLOCK" title="signal.SIG_UNBLOCK"><code class="xref py py-data docutils literal notranslate"><span class="pre">SIG_UNBLOCK</span></code></a>: The signals in <em>mask</em> are removed from the current
|
||
set of blocked signals. It is permissible to attempt to unblock a
|
||
signal which is not blocked.</p></li>
|
||
<li><p><a class="reference internal" href="#signal.SIG_SETMASK" title="signal.SIG_SETMASK"><code class="xref py py-data docutils literal notranslate"><span class="pre">SIG_SETMASK</span></code></a>: The set of blocked signals is set to the <em>mask</em>
|
||
argument.</p></li>
|
||
</ul>
|
||
<p><em>mask</em> is a set of signal numbers (e.g. {<code class="xref py py-const docutils literal notranslate"><span class="pre">signal.SIGINT</span></code>,
|
||
<code class="xref py py-const docutils literal notranslate"><span class="pre">signal.SIGTERM</span></code>}). Use <code class="docutils literal notranslate"><span class="pre">range(1,</span> <span class="pre">signal.NSIG)</span></code> for a full mask
|
||
including all signals.</p>
|
||
<p>For example, <code class="docutils literal notranslate"><span class="pre">signal.pthread_sigmask(signal.SIG_BLOCK,</span> <span class="pre">[])</span></code> reads the
|
||
signal mask of the calling thread.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix. See the man page <em class="manpage">sigprocmask(3)</em> and
|
||
<em class="manpage">pthread_sigmask(3)</em> for further information.</p>
|
||
<p>See also <a class="reference internal" href="#signal.pause" title="signal.pause"><code class="xref py py-func docutils literal notranslate"><span class="pre">pause()</span></code></a>, <a class="reference internal" href="#signal.sigpending" title="signal.sigpending"><code class="xref py py-func docutils literal notranslate"><span class="pre">sigpending()</span></code></a> and <a class="reference internal" href="#signal.sigwait" title="signal.sigwait"><code class="xref py py-func docutils literal notranslate"><span class="pre">sigwait()</span></code></a>.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.3.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="signal.setitimer">
|
||
<code class="descclassname">signal.</code><code class="descname">setitimer</code><span class="sig-paren">(</span><em>which</em>, <em>seconds</em>, <em>interval=0.0</em><span class="sig-paren">)</span><a class="headerlink" href="#signal.setitimer" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Sets given interval timer (one of <a class="reference internal" href="#signal.ITIMER_REAL" title="signal.ITIMER_REAL"><code class="xref py py-const docutils literal notranslate"><span class="pre">signal.ITIMER_REAL</span></code></a>,
|
||
<a class="reference internal" href="#signal.ITIMER_VIRTUAL" title="signal.ITIMER_VIRTUAL"><code class="xref py py-const docutils literal notranslate"><span class="pre">signal.ITIMER_VIRTUAL</span></code></a> or <a class="reference internal" href="#signal.ITIMER_PROF" title="signal.ITIMER_PROF"><code class="xref py py-const docutils literal notranslate"><span class="pre">signal.ITIMER_PROF</span></code></a>) specified
|
||
by <em>which</em> to fire after <em>seconds</em> (float is accepted, different from
|
||
<a class="reference internal" href="#signal.alarm" title="signal.alarm"><code class="xref py py-func docutils literal notranslate"><span class="pre">alarm()</span></code></a>) and after that every <em>interval</em> seconds (if <em>interval</em>
|
||
is non-zero). The interval timer specified by <em>which</em> can be cleared by
|
||
setting <em>seconds</em> to zero.</p>
|
||
<p>When an interval timer fires, a signal is sent to the process.
|
||
The signal sent is dependent on the timer being used;
|
||
<a class="reference internal" href="#signal.ITIMER_REAL" title="signal.ITIMER_REAL"><code class="xref py py-const docutils literal notranslate"><span class="pre">signal.ITIMER_REAL</span></code></a> will deliver <code class="xref py py-const docutils literal notranslate"><span class="pre">SIGALRM</span></code>,
|
||
<a class="reference internal" href="#signal.ITIMER_VIRTUAL" title="signal.ITIMER_VIRTUAL"><code class="xref py py-const docutils literal notranslate"><span class="pre">signal.ITIMER_VIRTUAL</span></code></a> sends <code class="xref py py-const docutils literal notranslate"><span class="pre">SIGVTALRM</span></code>,
|
||
and <a class="reference internal" href="#signal.ITIMER_PROF" title="signal.ITIMER_PROF"><code class="xref py py-const docutils literal notranslate"><span class="pre">signal.ITIMER_PROF</span></code></a> will deliver <code class="xref py py-const docutils literal notranslate"><span class="pre">SIGPROF</span></code>.</p>
|
||
<p>The old values are returned as a tuple: (delay, interval).</p>
|
||
<p>Attempting to pass an invalid interval timer will cause an
|
||
<a class="reference internal" href="#signal.ItimerError" title="signal.ItimerError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ItimerError</span></code></a>.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="signal.getitimer">
|
||
<code class="descclassname">signal.</code><code class="descname">getitimer</code><span class="sig-paren">(</span><em>which</em><span class="sig-paren">)</span><a class="headerlink" href="#signal.getitimer" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Returns current value of a given interval timer specified by <em>which</em>.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="signal.set_wakeup_fd">
|
||
<code class="descclassname">signal.</code><code class="descname">set_wakeup_fd</code><span class="sig-paren">(</span><em>fd</em>, <em>*</em>, <em>warn_on_full_buffer=True</em><span class="sig-paren">)</span><a class="headerlink" href="#signal.set_wakeup_fd" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Set the wakeup file descriptor to <em>fd</em>. When a signal is received, the
|
||
signal number is written as a single byte into the fd. This can be used by
|
||
a library to wakeup a poll or select call, allowing the signal to be fully
|
||
processed.</p>
|
||
<p>The old wakeup fd is returned (or -1 if file descriptor wakeup was not
|
||
enabled). If <em>fd</em> is -1, file descriptor wakeup is disabled.
|
||
If not -1, <em>fd</em> must be non-blocking. It is up to the library to remove
|
||
any bytes from <em>fd</em> before calling poll or select again.</p>
|
||
<p>When threads are enabled, this function can only be called from the main thread;
|
||
attempting to call it from other threads will cause a <a class="reference internal" href="exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ValueError</span></code></a>
|
||
exception to be raised.</p>
|
||
<p>There are two common ways to use this function. In both approaches,
|
||
you use the fd to wake up when a signal arrives, but then they
|
||
differ in how they determine <em>which</em> signal or signals have
|
||
arrived.</p>
|
||
<p>In the first approach, we read the data out of the fd’s buffer, and
|
||
the byte values give you the signal numbers. This is simple, but in
|
||
rare cases it can run into a problem: generally the fd will have a
|
||
limited amount of buffer space, and if too many signals arrive too
|
||
quickly, then the buffer may become full, and some signals may be
|
||
lost. If you use this approach, then you should set
|
||
<code class="docutils literal notranslate"><span class="pre">warn_on_full_buffer=True</span></code>, which will at least cause a warning
|
||
to be printed to stderr when signals are lost.</p>
|
||
<p>In the second approach, we use the wakeup fd <em>only</em> for wakeups,
|
||
and ignore the actual byte values. In this case, all we care about
|
||
is whether the fd’s buffer is empty or non-empty; a full buffer
|
||
doesn’t indicate a problem at all. If you use this approach, then
|
||
you should set <code class="docutils literal notranslate"><span class="pre">warn_on_full_buffer=False</span></code>, so that your users
|
||
are not confused by spurious warning messages.</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.5: </span>On Windows, the function now also supports socket handles.</p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.7: </span>Added <code class="docutils literal notranslate"><span class="pre">warn_on_full_buffer</span></code> parameter.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="signal.siginterrupt">
|
||
<code class="descclassname">signal.</code><code class="descname">siginterrupt</code><span class="sig-paren">(</span><em>signalnum</em>, <em>flag</em><span class="sig-paren">)</span><a class="headerlink" href="#signal.siginterrupt" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Change system call restart behaviour: if <em>flag</em> is <a class="reference internal" href="constants.html#False" title="False"><code class="xref py py-const docutils literal notranslate"><span class="pre">False</span></code></a>, system
|
||
calls will be restarted when interrupted by signal <em>signalnum</em>, otherwise
|
||
system calls will be interrupted. Returns nothing.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix (see the man page <em class="manpage">siginterrupt(3)</em>
|
||
for further information).</p>
|
||
<p>Note that installing a signal handler with <a class="reference internal" href="#module-signal" title="signal: Set handlers for asynchronous events."><code class="xref py py-func docutils literal notranslate"><span class="pre">signal()</span></code></a> will reset the
|
||
restart behaviour to interruptible by implicitly calling
|
||
<code class="xref c c-func docutils literal notranslate"><span class="pre">siginterrupt()</span></code> with a true <em>flag</em> value for the given signal.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="signal.signal">
|
||
<code class="descclassname">signal.</code><code class="descname">signal</code><span class="sig-paren">(</span><em>signalnum</em>, <em>handler</em><span class="sig-paren">)</span><a class="headerlink" href="#signal.signal" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Set the handler for signal <em>signalnum</em> to the function <em>handler</em>. <em>handler</em> can
|
||
be a callable Python object taking two arguments (see below), or one of the
|
||
special values <a class="reference internal" href="#signal.SIG_IGN" title="signal.SIG_IGN"><code class="xref py py-const docutils literal notranslate"><span class="pre">signal.SIG_IGN</span></code></a> or <a class="reference internal" href="#signal.SIG_DFL" title="signal.SIG_DFL"><code class="xref py py-const docutils literal notranslate"><span class="pre">signal.SIG_DFL</span></code></a>. The previous
|
||
signal handler will be returned (see the description of <a class="reference internal" href="#signal.getsignal" title="signal.getsignal"><code class="xref py py-func docutils literal notranslate"><span class="pre">getsignal()</span></code></a>
|
||
above). (See the Unix man page <em class="manpage">signal(2)</em>.)</p>
|
||
<p>When threads are enabled, this function can only be called from the main thread;
|
||
attempting to call it from other threads will cause a <a class="reference internal" href="exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ValueError</span></code></a>
|
||
exception to be raised.</p>
|
||
<p>The <em>handler</em> is called with two arguments: the signal number and the current
|
||
stack frame (<code class="docutils literal notranslate"><span class="pre">None</span></code> or a frame object; for a description of frame objects,
|
||
see the <a class="reference internal" href="../reference/datamodel.html#frame-objects"><span class="std std-ref">description in the type hierarchy</span></a> or see the
|
||
attribute descriptions in the <a class="reference internal" href="inspect.html#module-inspect" title="inspect: Extract information and source code from live objects."><code class="xref py py-mod docutils literal notranslate"><span class="pre">inspect</span></code></a> module).</p>
|
||
<p>On Windows, <a class="reference internal" href="#module-signal" title="signal: Set handlers for asynchronous events."><code class="xref py py-func docutils literal notranslate"><span class="pre">signal()</span></code></a> can only be called with <code class="xref py py-const docutils literal notranslate"><span class="pre">SIGABRT</span></code>,
|
||
<code class="xref py py-const docutils literal notranslate"><span class="pre">SIGFPE</span></code>, <code class="xref py py-const docutils literal notranslate"><span class="pre">SIGILL</span></code>, <code class="xref py py-const docutils literal notranslate"><span class="pre">SIGINT</span></code>, <code class="xref py py-const docutils literal notranslate"><span class="pre">SIGSEGV</span></code>,
|
||
<code class="xref py py-const docutils literal notranslate"><span class="pre">SIGTERM</span></code>, or <code class="xref py py-const docutils literal notranslate"><span class="pre">SIGBREAK</span></code>.
|
||
A <a class="reference internal" href="exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ValueError</span></code></a> will be raised in any other case.
|
||
Note that not all systems define the same set of signal names; an
|
||
<a class="reference internal" href="exceptions.html#AttributeError" title="AttributeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">AttributeError</span></code></a> will be raised if a signal name is not defined as
|
||
<code class="docutils literal notranslate"><span class="pre">SIG*</span></code> module level constant.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="signal.sigpending">
|
||
<code class="descclassname">signal.</code><code class="descname">sigpending</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#signal.sigpending" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Examine the set of signals that are pending for delivery to the calling
|
||
thread (i.e., the signals which have been raised while blocked). Return the
|
||
set of the pending signals.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix (see the man page <em class="manpage">sigpending(2)</em> for further
|
||
information).</p>
|
||
<p>See also <a class="reference internal" href="#signal.pause" title="signal.pause"><code class="xref py py-func docutils literal notranslate"><span class="pre">pause()</span></code></a>, <a class="reference internal" href="#signal.pthread_sigmask" title="signal.pthread_sigmask"><code class="xref py py-func docutils literal notranslate"><span class="pre">pthread_sigmask()</span></code></a> and <a class="reference internal" href="#signal.sigwait" title="signal.sigwait"><code class="xref py py-func docutils literal notranslate"><span class="pre">sigwait()</span></code></a>.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.3.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="signal.sigwait">
|
||
<code class="descclassname">signal.</code><code class="descname">sigwait</code><span class="sig-paren">(</span><em>sigset</em><span class="sig-paren">)</span><a class="headerlink" href="#signal.sigwait" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Suspend execution of the calling thread until the delivery of one of the
|
||
signals specified in the signal set <em>sigset</em>. The function accepts the signal
|
||
(removes it from the pending list of signals), and returns the signal number.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix (see the man page <em class="manpage">sigwait(3)</em> for further
|
||
information).</p>
|
||
<p>See also <a class="reference internal" href="#signal.pause" title="signal.pause"><code class="xref py py-func docutils literal notranslate"><span class="pre">pause()</span></code></a>, <a class="reference internal" href="#signal.pthread_sigmask" title="signal.pthread_sigmask"><code class="xref py py-func docutils literal notranslate"><span class="pre">pthread_sigmask()</span></code></a>, <a class="reference internal" href="#signal.sigpending" title="signal.sigpending"><code class="xref py py-func docutils literal notranslate"><span class="pre">sigpending()</span></code></a>,
|
||
<a class="reference internal" href="#signal.sigwaitinfo" title="signal.sigwaitinfo"><code class="xref py py-func docutils literal notranslate"><span class="pre">sigwaitinfo()</span></code></a> and <a class="reference internal" href="#signal.sigtimedwait" title="signal.sigtimedwait"><code class="xref py py-func docutils literal notranslate"><span class="pre">sigtimedwait()</span></code></a>.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.3.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="signal.sigwaitinfo">
|
||
<code class="descclassname">signal.</code><code class="descname">sigwaitinfo</code><span class="sig-paren">(</span><em>sigset</em><span class="sig-paren">)</span><a class="headerlink" href="#signal.sigwaitinfo" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Suspend execution of the calling thread until the delivery of one of the
|
||
signals specified in the signal set <em>sigset</em>. The function accepts the
|
||
signal and removes it from the pending list of signals. If one of the
|
||
signals in <em>sigset</em> is already pending for the calling thread, the function
|
||
will return immediately with information about that signal. The signal
|
||
handler is not called for the delivered signal. The function raises an
|
||
<a class="reference internal" href="exceptions.html#InterruptedError" title="InterruptedError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">InterruptedError</span></code></a> if it is interrupted by a signal that is not in
|
||
<em>sigset</em>.</p>
|
||
<p>The return value is an object representing the data contained in the
|
||
<code class="xref c c-type docutils literal notranslate"><span class="pre">siginfo_t</span></code> structure, namely: <code class="xref py py-attr docutils literal notranslate"><span class="pre">si_signo</span></code>, <code class="xref py py-attr docutils literal notranslate"><span class="pre">si_code</span></code>,
|
||
<code class="xref py py-attr docutils literal notranslate"><span class="pre">si_errno</span></code>, <code class="xref py py-attr docutils literal notranslate"><span class="pre">si_pid</span></code>, <code class="xref py py-attr docutils literal notranslate"><span class="pre">si_uid</span></code>, <code class="xref py py-attr docutils literal notranslate"><span class="pre">si_status</span></code>,
|
||
<code class="xref py py-attr docutils literal notranslate"><span class="pre">si_band</span></code>.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix (see the man page <em class="manpage">sigwaitinfo(2)</em> for further
|
||
information).</p>
|
||
<p>See also <a class="reference internal" href="#signal.pause" title="signal.pause"><code class="xref py py-func docutils literal notranslate"><span class="pre">pause()</span></code></a>, <a class="reference internal" href="#signal.sigwait" title="signal.sigwait"><code class="xref py py-func docutils literal notranslate"><span class="pre">sigwait()</span></code></a> and <a class="reference internal" href="#signal.sigtimedwait" title="signal.sigtimedwait"><code class="xref py py-func docutils literal notranslate"><span class="pre">sigtimedwait()</span></code></a>.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.3.</span></p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.5: </span>The function is now retried if interrupted by a signal not in <em>sigset</em>
|
||
and the signal handler does not raise an exception (see <span class="target" id="index-0"></span><a class="pep reference external" href="https://www.python.org/dev/peps/pep-0475"><strong>PEP 475</strong></a> for
|
||
the rationale).</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="signal.sigtimedwait">
|
||
<code class="descclassname">signal.</code><code class="descname">sigtimedwait</code><span class="sig-paren">(</span><em>sigset</em>, <em>timeout</em><span class="sig-paren">)</span><a class="headerlink" href="#signal.sigtimedwait" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Like <a class="reference internal" href="#signal.sigwaitinfo" title="signal.sigwaitinfo"><code class="xref py py-func docutils literal notranslate"><span class="pre">sigwaitinfo()</span></code></a>, but takes an additional <em>timeout</em> argument
|
||
specifying a timeout. If <em>timeout</em> is specified as <code class="xref py py-const docutils literal notranslate"><span class="pre">0</span></code>, a poll is
|
||
performed. Returns <a class="reference internal" href="constants.html#None" title="None"><code class="xref py py-const docutils literal notranslate"><span class="pre">None</span></code></a> if a timeout occurs.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix (see the man page <em class="manpage">sigtimedwait(2)</em> for further
|
||
information).</p>
|
||
<p>See also <a class="reference internal" href="#signal.pause" title="signal.pause"><code class="xref py py-func docutils literal notranslate"><span class="pre">pause()</span></code></a>, <a class="reference internal" href="#signal.sigwait" title="signal.sigwait"><code class="xref py py-func docutils literal notranslate"><span class="pre">sigwait()</span></code></a> and <a class="reference internal" href="#signal.sigwaitinfo" title="signal.sigwaitinfo"><code class="xref py py-func docutils literal notranslate"><span class="pre">sigwaitinfo()</span></code></a>.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.3.</span></p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.5: </span>The function is now retried with the recomputed <em>timeout</em> if interrupted
|
||
by a signal not in <em>sigset</em> and the signal handler does not raise an
|
||
exception (see <span class="target" id="index-1"></span><a class="pep reference external" href="https://www.python.org/dev/peps/pep-0475"><strong>PEP 475</strong></a> for the rationale).</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
</div>
|
||
<div class="section" id="example">
|
||
<span id="signal-example"></span><h2>Example<a class="headerlink" href="#example" title="Permalink to this headline">¶</a></h2>
|
||
<p>Here is a minimal example program. It uses the <a class="reference internal" href="#signal.alarm" title="signal.alarm"><code class="xref py py-func docutils literal notranslate"><span class="pre">alarm()</span></code></a> function to limit
|
||
the time spent waiting to open a file; this is useful if the file is for a
|
||
serial device that may not be turned on, which would normally cause the
|
||
<a class="reference internal" href="os.html#os.open" title="os.open"><code class="xref py py-func docutils literal notranslate"><span class="pre">os.open()</span></code></a> to hang indefinitely. The solution is to set a 5-second alarm
|
||
before opening the file; if the operation takes too long, the alarm signal will
|
||
be sent, and the handler raises an exception.</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">signal</span><span class="o">,</span> <span class="nn">os</span>
|
||
|
||
<span class="k">def</span> <span class="nf">handler</span><span class="p">(</span><span class="n">signum</span><span class="p">,</span> <span class="n">frame</span><span class="p">):</span>
|
||
<span class="nb">print</span><span class="p">(</span><span class="s1">'Signal handler called with signal'</span><span class="p">,</span> <span class="n">signum</span><span class="p">)</span>
|
||
<span class="k">raise</span> <span class="ne">OSError</span><span class="p">(</span><span class="s2">"Couldn't open device!"</span><span class="p">)</span>
|
||
|
||
<span class="c1"># Set the signal handler and a 5-second alarm</span>
|
||
<span class="n">signal</span><span class="o">.</span><span class="n">signal</span><span class="p">(</span><span class="n">signal</span><span class="o">.</span><span class="n">SIGALRM</span><span class="p">,</span> <span class="n">handler</span><span class="p">)</span>
|
||
<span class="n">signal</span><span class="o">.</span><span class="n">alarm</span><span class="p">(</span><span class="mi">5</span><span class="p">)</span>
|
||
|
||
<span class="c1"># This open() may hang indefinitely</span>
|
||
<span class="n">fd</span> <span class="o">=</span> <span class="n">os</span><span class="o">.</span><span class="n">open</span><span class="p">(</span><span class="s1">'/dev/ttyS0'</span><span class="p">,</span> <span class="n">os</span><span class="o">.</span><span class="n">O_RDWR</span><span class="p">)</span>
|
||
|
||
<span class="n">signal</span><span class="o">.</span><span class="n">alarm</span><span class="p">(</span><span class="mi">0</span><span class="p">)</span> <span class="c1"># Disable the alarm</span>
|
||
</pre></div>
|
||
</div>
|
||
</div>
|
||
<div class="section" id="note-on-sigpipe">
|
||
<h2>Note on SIGPIPE<a class="headerlink" href="#note-on-sigpipe" title="Permalink to this headline">¶</a></h2>
|
||
<p>Piping output of your program to tools like <em class="manpage">head(1)</em> will
|
||
cause a <code class="xref py py-const docutils literal notranslate"><span class="pre">SIGPIPE</span></code> signal to be sent to your process when the receiver
|
||
of its standard output closes early. This results in an exception
|
||
like <code class="code docutils literal notranslate"><span class="pre">BrokenPipeError:</span> <span class="pre">[Errno</span> <span class="pre">32]</span> <span class="pre">Broken</span> <span class="pre">pipe</span></code>. To handle this
|
||
case, wrap your entry point to catch this exception as follows:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">os</span>
|
||
<span class="kn">import</span> <span class="nn">sys</span>
|
||
|
||
<span class="k">def</span> <span class="nf">main</span><span class="p">():</span>
|
||
<span class="k">try</span><span class="p">:</span>
|
||
<span class="c1"># simulate large output (your code replaces this loop)</span>
|
||
<span class="k">for</span> <span class="n">x</span> <span class="ow">in</span> <span class="nb">range</span><span class="p">(</span><span class="mi">10000</span><span class="p">):</span>
|
||
<span class="nb">print</span><span class="p">(</span><span class="s2">"y"</span><span class="p">)</span>
|
||
<span class="c1"># flush output here to force SIGPIPE to be triggered</span>
|
||
<span class="c1"># while inside this try block.</span>
|
||
<span class="n">sys</span><span class="o">.</span><span class="n">stdout</span><span class="o">.</span><span class="n">flush</span><span class="p">()</span>
|
||
<span class="k">except</span> <span class="ne">BrokenPipeError</span><span class="p">:</span>
|
||
<span class="c1"># Python flushes standard streams on exit; redirect remaining output</span>
|
||
<span class="c1"># to devnull to avoid another BrokenPipeError at shutdown</span>
|
||
<span class="n">devnull</span> <span class="o">=</span> <span class="n">os</span><span class="o">.</span><span class="n">open</span><span class="p">(</span><span class="n">os</span><span class="o">.</span><span class="n">devnull</span><span class="p">,</span> <span class="n">os</span><span class="o">.</span><span class="n">O_WRONLY</span><span class="p">)</span>
|
||
<span class="n">os</span><span class="o">.</span><span class="n">dup2</span><span class="p">(</span><span class="n">devnull</span><span class="p">,</span> <span class="n">sys</span><span class="o">.</span><span class="n">stdout</span><span class="o">.</span><span class="n">fileno</span><span class="p">())</span>
|
||
<span class="n">sys</span><span class="o">.</span><span class="n">exit</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span> <span class="c1"># Python exits with error code 1 on EPIPE</span>
|
||
|
||
<span class="k">if</span> <span class="vm">__name__</span> <span class="o">==</span> <span class="s1">'__main__'</span><span class="p">:</span>
|
||
<span class="n">main</span><span class="p">()</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Do not set <code class="xref py py-const docutils literal notranslate"><span class="pre">SIGPIPE</span></code>’s disposition to <a class="reference internal" href="#signal.SIG_DFL" title="signal.SIG_DFL"><code class="xref py py-const docutils literal notranslate"><span class="pre">SIG_DFL</span></code></a>
|
||
in order to avoid <a class="reference internal" href="exceptions.html#BrokenPipeError" title="BrokenPipeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">BrokenPipeError</span></code></a>. Doing that would cause
|
||
your program to exit unexpectedly also whenever any socket connection
|
||
is interrupted while your program is still writing to it.</p>
|
||
</div>
|
||
</div>
|
||
|
||
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
|
||
<div class="sphinxsidebarwrapper">
|
||
<h3><a href="../contents.html">Table of Contents</a></h3>
|
||
<ul>
|
||
<li><a class="reference internal" href="#"><code class="xref py py-mod docutils literal notranslate"><span class="pre">signal</span></code> — Set handlers for asynchronous events</a><ul>
|
||
<li><a class="reference internal" href="#general-rules">General rules</a><ul>
|
||
<li><a class="reference internal" href="#execution-of-python-signal-handlers">Execution of Python signal handlers</a></li>
|
||
<li><a class="reference internal" href="#signals-and-threads">Signals and threads</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#module-contents">Module contents</a></li>
|
||
<li><a class="reference internal" href="#example">Example</a></li>
|
||
<li><a class="reference internal" href="#note-on-sigpipe">Note on SIGPIPE</a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
|
||
<h4>Previous topic</h4>
|
||
<p class="topless"><a href="asynchat.html"
|
||
title="previous chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">asynchat</span></code> — Asynchronous socket command/response handler</a></p>
|
||
<h4>Next topic</h4>
|
||
<p class="topless"><a href="mmap.html"
|
||
title="next chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">mmap</span></code> — Memory-mapped file support</a></p>
|
||
<div role="note" aria-label="source link">
|
||
<h3>This Page</h3>
|
||
<ul class="this-page-menu">
|
||
<li><a href="../bugs.html">Report a Bug</a></li>
|
||
<li>
|
||
<a href="https://github.com/python/cpython/blob/3.7/Doc/library/signal.rst"
|
||
rel="nofollow">Show Source
|
||
</a>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="clearer"></div>
|
||
</div>
|
||
<div class="related" role="navigation" aria-label="related navigation">
|
||
<h3>Navigation</h3>
|
||
<ul>
|
||
<li class="right" style="margin-right: 10px">
|
||
<a href="../genindex.html" title="General Index"
|
||
>index</a></li>
|
||
<li class="right" >
|
||
<a href="../py-modindex.html" title="Python Module Index"
|
||
>modules</a> |</li>
|
||
<li class="right" >
|
||
<a href="mmap.html" title="mmap — Memory-mapped file support"
|
||
>next</a> |</li>
|
||
<li class="right" >
|
||
<a href="asynchat.html" title="asynchat — Asynchronous socket command/response handler"
|
||
>previous</a> |</li>
|
||
<li><img src="../_static/py.png" alt=""
|
||
style="vertical-align: middle; margin-top: -1px"/></li>
|
||
<li><a href="https://www.python.org/">Python</a> »</li>
|
||
<li>
|
||
<span class="language_switcher_placeholder">en</span>
|
||
<span class="version_switcher_placeholder">3.7.4</span>
|
||
<a href="../index.html">Documentation </a> »
|
||
</li>
|
||
|
||
<li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> »</li>
|
||
<li class="nav-item nav-item-2"><a href="ipc.html" >Networking and Interprocess Communication</a> »</li>
|
||
<li class="right">
|
||
|
||
|
||
<div class="inline-search" style="display: none" role="search">
|
||
<form class="inline-search" action="../search.html" method="get">
|
||
<input placeholder="Quick search" type="text" name="q" />
|
||
<input type="submit" value="Go" />
|
||
<input type="hidden" name="check_keywords" value="yes" />
|
||
<input type="hidden" name="area" value="default" />
|
||
</form>
|
||
</div>
|
||
<script type="text/javascript">$('.inline-search').show(0);</script>
|
||
|
|
||
</li>
|
||
|
||
</ul>
|
||
</div>
|
||
<div class="footer">
|
||
© <a href="../copyright.html">Copyright</a> 2001-2019, Python Software Foundation.
|
||
<br />
|
||
The Python Software Foundation is a non-profit corporation.
|
||
<a href="https://www.python.org/psf/donations/">Please donate.</a>
|
||
<br />
|
||
Last updated on Jul 13, 2019.
|
||
<a href="../bugs.html">Found a bug</a>?
|
||
<br />
|
||
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 2.0.1.
|
||
</div>
|
||
|
||
</body>
|
||
</html> |