<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>27.2. faulthandler — Dump the Python traceback — Python 3.5.3 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">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../',
VERSION: '3.5.3',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</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/sidebar.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within Python 3.5.3 documentation"
href="../_static/opensearch.xml"/>
<link rel="author" title="About these documents" href="../about.html" />
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="top" title="Python 3.5.3 documentation" href="../contents.html" />
<link rel="up" title="27. Debugging and Profiling" href="debug.html" />
<link rel="next" title="27.3. pdb — The Python Debugger" href="pdb.html" />
<link rel="prev" title="27.1. bdb — Debugger framework" href="bdb.html" />
<link rel="shortcut icon" type="image/png" href="../_static/py.png" />
<script type="text/javascript" src="../_static/copybutton.js"></script>
<script type="text/javascript" src="../_static/version_switch.js"></script>
</head>
<body role="document">
<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="pdb.html" title="27.3. pdb — The Python Debugger"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="bdb.html" title="27.1. bdb — Debugger framework"
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="version_switcher_placeholder">3.5.3</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="debug.html" accesskey="U">27. Debugging and Profiling</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-faulthandler">
<span id="faulthandler-dump-the-python-traceback"></span><h1>27.2. <a class="reference internal" href="#module-faulthandler" title="faulthandler: Dump the Python traceback."><code class="xref py py-mod docutils literal"><span class="pre">faulthandler</span></code></a> — Dump the Python traceback<a class="headerlink" href="#module-faulthandler" title="Permalink to this headline">¶</a></h1>
<div class="versionadded">
<p><span class="versionmodified">New in version 3.3.</span></p>
</div>
<hr class="docutils" />
<p>This module contains functions to dump Python tracebacks explicitly, on a fault,
after a timeout, or on a user signal. Call <a class="reference internal" href="#faulthandler.enable" title="faulthandler.enable"><code class="xref py py-func docutils literal"><span class="pre">faulthandler.enable()</span></code></a> to
install fault handlers for the <code class="xref py py-const docutils literal"><span class="pre">SIGSEGV</span></code>, <code class="xref py py-const docutils literal"><span class="pre">SIGFPE</span></code>,
<code class="xref py py-const docutils literal"><span class="pre">SIGABRT</span></code>, <code class="xref py py-const docutils literal"><span class="pre">SIGBUS</span></code>, and <code class="xref py py-const docutils literal"><span class="pre">SIGILL</span></code> signals. You can also
enable them at startup by setting the <span class="target" id="index-0"></span><a class="reference internal" href="../using/cmdline.html#envvar-PYTHONFAULTHANDLER"><code class="xref std std-envvar docutils literal"><span class="pre">PYTHONFAULTHANDLER</span></code></a> environment
variable or by using the <a class="reference internal" href="../using/cmdline.html#cmdoption-X"><code class="xref std std-option docutils literal"><span class="pre">-X</span></code></a> <code class="docutils literal"><span class="pre">faulthandler</span></code> command line option.</p>
<p>The fault handler is compatible with system fault handlers like Apport or the
Windows fault handler. The module uses an alternative stack for signal handlers
if the <code class="xref c c-func docutils literal"><span class="pre">sigaltstack()</span></code> function is available. This allows it to dump the
traceback even on a stack overflow.</p>
<p>The fault handler is called on catastrophic cases and therefore can only use
signal-safe functions (e.g. it cannot allocate memory on the heap). Because of
this limitation traceback dumping is minimal compared to normal Python
tracebacks:</p>
<ul class="simple">
<li>Only ASCII is supported. The <code class="docutils literal"><span class="pre">backslashreplace</span></code> error handler is used on
encoding.</li>
<li>Each string is limited to 500 characters.</li>
<li>Only the filename, the function name and the line number are
displayed. (no source code)</li>
<li>It is limited to 100 frames and 100 threads.</li>
<li>The order is reversed: the most recent call is shown first.</li>
</ul>
<p>By default, the Python traceback is written to <a class="reference internal" href="sys.html#sys.stderr" title="sys.stderr"><code class="xref py py-data docutils literal"><span class="pre">sys.stderr</span></code></a>. To see
tracebacks, applications must be run in the terminal. A log file can
alternatively be passed to <a class="reference internal" href="#faulthandler.enable" title="faulthandler.enable"><code class="xref py py-func docutils literal"><span class="pre">faulthandler.enable()</span></code></a>.</p>
<p>The module is implemented in C, so tracebacks can be dumped on a crash or when
Python is deadlocked.</p>
<div class="section" id="dumping-the-traceback">
<h2>27.2.1. Dumping the traceback<a class="headerlink" href="#dumping-the-traceback" title="Permalink to this headline">¶</a></h2>
<dl class="function">
<dt id="faulthandler.dump_traceback">
<code class="descclassname">faulthandler.</code><code class="descname">dump_traceback</code><span class="sig-paren">(</span><em>file=sys.stderr</em>, <em>all_threads=True</em><span class="sig-paren">)</span><a class="headerlink" href="#faulthandler.dump_traceback" title="Permalink to this definition">¶</a></dt>
<dd><p>Dump the tracebacks of all threads into <em>file</em>. If <em>all_threads</em> is
<code class="docutils literal"><span class="pre">False</span></code>, dump only the current thread.</p>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 3.5: </span>Added support for passing file descriptor to this function.</p>
</div>
</dd></dl>
</div>
<div class="section" id="fault-handler-state">
<h2>27.2.2. Fault handler state<a class="headerlink" href="#fault-handler-state" title="Permalink to this headline">¶</a></h2>
<dl class="function">
<dt id="faulthandler.enable">
<code class="descclassname">faulthandler.</code><code class="descname">enable</code><span class="sig-paren">(</span><em>file=sys.stderr</em>, <em>all_threads=True</em><span class="sig-paren">)</span><a class="headerlink" href="#faulthandler.enable" title="Permalink to this definition">¶</a></dt>
<dd><p>Enable the fault handler: install handlers for the <code class="xref py py-const docutils literal"><span class="pre">SIGSEGV</span></code>,
<code class="xref py py-const docutils literal"><span class="pre">SIGFPE</span></code>, <code class="xref py py-const docutils literal"><span class="pre">SIGABRT</span></code>, <code class="xref py py-const docutils literal"><span class="pre">SIGBUS</span></code> and <code class="xref py py-const docutils literal"><span class="pre">SIGILL</span></code>
signals to dump the Python traceback. If <em>all_threads</em> is <code class="docutils literal"><span class="pre">True</span></code>,
produce tracebacks for every running thread. Otherwise, dump only the current
thread.</p>
<p>The <em>file</em> must be kept open until the fault handler is disabled: see
<a class="reference internal" href="#faulthandler-fd"><span>issue with file descriptors</span></a>.</p>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 3.5: </span>Added support for passing file descriptor to this function.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="faulthandler.disable">
<code class="descclassname">faulthandler.</code><code class="descname">disable</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#faulthandler.disable" title="Permalink to this definition">¶</a></dt>
<dd><p>Disable the fault handler: uninstall the signal handlers installed by
<a class="reference internal" href="#faulthandler.enable" title="faulthandler.enable"><code class="xref py py-func docutils literal"><span class="pre">enable()</span></code></a>.</p>
</dd></dl>
<dl class="function">
<dt id="faulthandler.is_enabled">
<code class="descclassname">faulthandler.</code><code class="descname">is_enabled</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#faulthandler.is_enabled" title="Permalink to this definition">¶</a></dt>
<dd><p>Check if the fault handler is enabled.</p>
</dd></dl>
</div>
<div class="section" id="dumping-the-tracebacks-after-a-timeout">
<h2>27.2.3. Dumping the tracebacks after a timeout<a class="headerlink" href="#dumping-the-tracebacks-after-a-timeout" title="Permalink to this headline">¶</a></h2>
<dl class="function">
<dt id="faulthandler.dump_traceback_later">
<code class="descclassname">faulthandler.</code><code class="descname">dump_traceback_later</code><span class="sig-paren">(</span><em>timeout</em>, <em>repeat=False</em>, <em>file=sys.stderr</em>, <em>exit=False</em><span class="sig-paren">)</span><a class="headerlink" href="#faulthandler.dump_traceback_later" title="Permalink to this definition">¶</a></dt>
<dd><p>Dump the tracebacks of all threads, after a timeout of <em>timeout</em> seconds, or
every <em>timeout</em> seconds if <em>repeat</em> is <code class="docutils literal"><span class="pre">True</span></code>. If <em>exit</em> is <code class="docutils literal"><span class="pre">True</span></code>, call
<code class="xref c c-func docutils literal"><span class="pre">_exit()</span></code> with status=1 after dumping the tracebacks. (Note
<code class="xref c c-func docutils literal"><span class="pre">_exit()</span></code> exits the process immediately, which means it doesn’t do any
cleanup like flushing file buffers.) If the function is called twice, the new
call replaces previous parameters and resets the timeout. The timer has a
sub-second resolution.</p>
<p>The <em>file</em> must be kept open until the traceback is dumped or
<a class="reference internal" href="#faulthandler.cancel_dump_traceback_later" title="faulthandler.cancel_dump_traceback_later"><code class="xref py py-func docutils literal"><span class="pre">cancel_dump_traceback_later()</span></code></a> is called: see <a class="reference internal" href="#faulthandler-fd"><span>issue with file
descriptors</span></a>.</p>
<p>This function is implemented using a watchdog thread and therefore is not
available if Python is compiled with threads disabled.</p>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 3.5: </span>Added support for passing file descriptor to this function.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="faulthandler.cancel_dump_traceback_later">
<code class="descclassname">faulthandler.</code><code class="descname">cancel_dump_traceback_later</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#faulthandler.cancel_dump_traceback_later" title="Permalink to this definition">¶</a></dt>
<dd><p>Cancel the last call to <a class="reference internal" href="#faulthandler.dump_traceback_later" title="faulthandler.dump_traceback_later"><code class="xref py py-func docutils literal"><span class="pre">dump_traceback_later()</span></code></a>.</p>
</dd></dl>
</div>
<div class="section" id="dumping-the-traceback-on-a-user-signal">
<h2>27.2.4. Dumping the traceback on a user signal<a class="headerlink" href="#dumping-the-traceback-on-a-user-signal" title="Permalink to this headline">¶</a></h2>
<dl class="function">
<dt id="faulthandler.register">
<code class="descclassname">faulthandler.</code><code class="descname">register</code><span class="sig-paren">(</span><em>signum</em>, <em>file=sys.stderr</em>, <em>all_threads=True</em>, <em>chain=False</em><span class="sig-paren">)</span><a class="headerlink" href="#faulthandler.register" title="Permalink to this definition">¶</a></dt>
<dd><p>Register a user signal: install a handler for the <em>signum</em> signal to dump
the traceback of all threads, or of the current thread if <em>all_threads</em> is
<code class="docutils literal"><span class="pre">False</span></code>, into <em>file</em>. Call the previous handler if chain is <code class="docutils literal"><span class="pre">True</span></code>.</p>
<p>The <em>file</em> must be kept open until the signal is unregistered by
<a class="reference internal" href="#faulthandler.unregister" title="faulthandler.unregister"><code class="xref py py-func docutils literal"><span class="pre">unregister()</span></code></a>: see <a class="reference internal" href="#faulthandler-fd"><span>issue with file descriptors</span></a>.</p>
<p>Not available on Windows.</p>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 3.5: </span>Added support for passing file descriptor to this function.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="faulthandler.unregister">
<code class="descclassname">faulthandler.</code><code class="descname">unregister</code><span class="sig-paren">(</span><em>signum</em><span class="sig-paren">)</span><a class="headerlink" href="#faulthandler.unregister" title="Permalink to this definition">¶</a></dt>
<dd><p>Unregister a user signal: uninstall the handler of the <em>signum</em> signal
installed by <a class="reference internal" href="#faulthandler.register" title="faulthandler.register"><code class="xref py py-func docutils literal"><span class="pre">register()</span></code></a>. Return <code class="docutils literal"><span class="pre">True</span></code> if the signal was registered,
<code class="docutils literal"><span class="pre">False</span></code> otherwise.</p>
<p>Not available on Windows.</p>
</dd></dl>
</div>
<div class="section" id="issue-with-file-descriptors">
<span id="faulthandler-fd"></span><h2>27.2.5. Issue with file descriptors<a class="headerlink" href="#issue-with-file-descriptors" title="Permalink to this headline">¶</a></h2>
<p><a class="reference internal" href="#faulthandler.enable" title="faulthandler.enable"><code class="xref py py-func docutils literal"><span class="pre">enable()</span></code></a>, <a class="reference internal" href="#faulthandler.dump_traceback_later" title="faulthandler.dump_traceback_later"><code class="xref py py-func docutils literal"><span class="pre">dump_traceback_later()</span></code></a> and <a class="reference internal" href="#faulthandler.register" title="faulthandler.register"><code class="xref py py-func docutils literal"><span class="pre">register()</span></code></a> keep the
file descriptor of their <em>file</em> argument. If the file is closed and its file
descriptor is reused by a new file, or if <a class="reference internal" href="os.html#os.dup2" title="os.dup2"><code class="xref py py-func docutils literal"><span class="pre">os.dup2()</span></code></a> is used to replace
the file descriptor, the traceback will be written into a different file. Call
these functions again each time that the file is replaced.</p>
</div>
<div class="section" id="example">
<h2>27.2.6. Example<a class="headerlink" href="#example" title="Permalink to this headline">¶</a></h2>
<p>Example of a segmentation fault on Linux with and without enabling the fault
handler:</p>
<div class="highlight-sh"><div class="highlight"><pre><span></span>$ python3 -c <span class="s2">"import ctypes; ctypes.string_at(0)"</span>
Segmentation fault
$ python3 -q -X faulthandler
>>> import ctypes
>>> ctypes.string_at<span class="o">(</span>0<span class="o">)</span>
Fatal Python error: Segmentation fault
Current thread 0x00007fb899f39700 <span class="o">(</span>most recent call first<span class="o">)</span>:
File <span class="s2">"/home/python/cpython/Lib/ctypes/__init__.py"</span>, line <span class="m">486</span> in string_at
File <span class="s2">"<stdin>"</span>, line <span class="m">1</span> in <module>
Segmentation fault
</pre></div>
</div>
</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="#">27.2. <code class="docutils literal"><span class="pre">faulthandler</span></code> — Dump the Python traceback</a><ul>
<li><a class="reference internal" href="#dumping-the-traceback">27.2.1. Dumping the traceback</a></li>
<li><a class="reference internal" href="#fault-handler-state">27.2.2. Fault handler state</a></li>
<li><a class="reference internal" href="#dumping-the-tracebacks-after-a-timeout">27.2.3. Dumping the tracebacks after a timeout</a></li>
<li><a class="reference internal" href="#dumping-the-traceback-on-a-user-signal">27.2.4. Dumping the traceback on a user signal</a></li>
<li><a class="reference internal" href="#issue-with-file-descriptors">27.2.5. Issue with file descriptors</a></li>
<li><a class="reference internal" href="#example">27.2.6. Example</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="bdb.html"
title="previous chapter">27.1. <code class="docutils literal"><span class="pre">bdb</span></code> — Debugger framework</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="pdb.html"
title="next chapter">27.3. <code class="docutils literal"><span class="pre">pdb</span></code> — The Python Debugger</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="../_sources/library/faulthandler.txt"
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="pdb.html" title="27.3. pdb — The Python Debugger"
>next</a> |</li>
<li class="right" >
<a href="bdb.html" title="27.1. bdb — Debugger framework"
>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="version_switcher_placeholder">3.5.3</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="debug.html" >27. Debugging and Profiling</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-2017, 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 Jan 20, 2017.
<a href="../bugs.html">Found a bug</a>?
<br />
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.3.3.
</div>
</body>
</html>
