<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta charset="utf-8" />
<title>faulthandler — Dump the Python traceback — Python 3.7.10 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.10 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="pdb — The Python Debugger" href="pdb.html" />
<link rel="prev" title="bdb — Debugger framework" href="bdb.html" />
<link rel="shortcut icon" type="image/png" href="../_static/py.png" />
<link rel="canonical" href="https://docs.python.org/3/library/faulthandler.html" />
<script type="text/javascript" src="../_static/copybutton.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="pdb.html" title="pdb — The Python Debugger"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="bdb.html" title="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>
<a href="../index.html">3.7.10 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">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><a class="reference internal" href="#module-faulthandler" title="faulthandler: Dump the Python traceback."><code class="xref py py-mod docutils literal notranslate"><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 added">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 notranslate"><span class="pre">faulthandler.enable()</span></code></a> to
install fault handlers for the <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">SIGFPE</span></code>,
<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">SIGBUS</span></code>, and <code class="xref py py-const docutils literal notranslate"><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 notranslate"><span class="pre">PYTHONFAULTHANDLER</span></code></a> environment
variable or by using the <a class="reference internal" href="../using/cmdline.html#id5"><code class="xref std std-option docutils literal notranslate"><span class="pre">-X</span></code></a> <code class="docutils literal notranslate"><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 notranslate"><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><p>Only ASCII is supported. The <code class="docutils literal notranslate"><span class="pre">backslashreplace</span></code> error handler is used on
encoding.</p></li>
<li><p>Each string is limited to 500 characters.</p></li>
<li><p>Only the filename, the function name and the line number are
displayed. (no source code)</p></li>
<li><p>It is limited to 100 frames and 100 threads.</p></li>
<li><p>The order is reversed: the most recent call is shown first.</p></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 notranslate"><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 notranslate"><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>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="sig-prename descclassname">faulthandler.</code><code class="sig-name descname">dump_traceback</code><span class="sig-paren">(</span><em class="sig-param">file=sys.stderr</em>, <em class="sig-param">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 notranslate"><span class="pre">False</span></code>, dump only the current thread.</p>
<div class="versionchanged">
<p><span class="versionmodified changed">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>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="sig-prename descclassname">faulthandler.</code><code class="sig-name descname">enable</code><span class="sig-paren">(</span><em class="sig-param">file=sys.stderr</em>, <em class="sig-param">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 notranslate"><span class="pre">SIGSEGV</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">SIGABRT</span></code>, <code class="xref py py-const docutils literal notranslate"><span class="pre">SIGBUS</span></code> and <code class="xref py py-const docutils literal notranslate"><span class="pre">SIGILL</span></code>
signals to dump the Python traceback. If <em>all_threads</em> is <code class="docutils literal notranslate"><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 class="std std-ref">issue with file descriptors</span></a>.</p>
<div class="versionchanged">
<p><span class="versionmodified changed">Changed in version 3.5: </span>Added support for passing file descriptor to this function.</p>
</div>
<div class="versionchanged">
<p><span class="versionmodified changed">Changed in version 3.6: </span>On Windows, a handler for Windows exception is also installed.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="faulthandler.disable">
<code class="sig-prename descclassname">faulthandler.</code><code class="sig-name 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 notranslate"><span class="pre">enable()</span></code></a>.</p>
</dd></dl>
<dl class="function">
<dt id="faulthandler.is_enabled">
<code class="sig-prename descclassname">faulthandler.</code><code class="sig-name 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>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="sig-prename descclassname">faulthandler.</code><code class="sig-name descname">dump_traceback_later</code><span class="sig-paren">(</span><em class="sig-param">timeout</em>, <em class="sig-param">repeat=False</em>, <em class="sig-param">file=sys.stderr</em>, <em class="sig-param">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 notranslate"><span class="pre">True</span></code>. If <em>exit</em> is <code class="docutils literal notranslate"><span class="pre">True</span></code>, call
<code class="xref c c-func docutils literal notranslate"><span class="pre">_exit()</span></code> with status=1 after dumping the tracebacks. (Note
<code class="xref c c-func docutils literal notranslate"><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 notranslate"><span class="pre">cancel_dump_traceback_later()</span></code></a> is called: see <a class="reference internal" href="#faulthandler-fd"><span class="std std-ref">issue with file
descriptors</span></a>.</p>
<p>This function is implemented using a watchdog thread.</p>
<div class="versionchanged">
<p><span class="versionmodified changed">Changed in version 3.7: </span>This function is now always available.</p>
</div>
<div class="versionchanged">
<p><span class="versionmodified changed">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="sig-prename descclassname">faulthandler.</code><code class="sig-name 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 notranslate"><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>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="sig-prename descclassname">faulthandler.</code><code class="sig-name descname">register</code><span class="sig-paren">(</span><em class="sig-param">signum</em>, <em class="sig-param">file=sys.stderr</em>, <em class="sig-param">all_threads=True</em>, <em class="sig-param">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 notranslate"><span class="pre">False</span></code>, into <em>file</em>. Call the previous handler if chain is <code class="docutils literal notranslate"><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 notranslate"><span class="pre">unregister()</span></code></a>: see <a class="reference internal" href="#faulthandler-fd"><span class="std std-ref">issue with file descriptors</span></a>.</p>
<p>Not available on Windows.</p>
<div class="versionchanged">
<p><span class="versionmodified changed">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="sig-prename descclassname">faulthandler.</code><code class="sig-name descname">unregister</code><span class="sig-paren">(</span><em class="sig-param">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 notranslate"><span class="pre">register()</span></code></a>. Return <code class="docutils literal notranslate"><span class="pre">True</span></code> if the signal was registered,
<code class="docutils literal notranslate"><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>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 notranslate"><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 notranslate"><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 notranslate"><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 notranslate"><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>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-shell-session notranslate"><div class="highlight"><pre><span></span><span class="gp">$</span> python3 -c <span class="s2">"import ctypes; ctypes.string_at(0)"</span>
<span class="go">Segmentation fault</span>
<span class="gp">$</span> python3 -q -X faulthandler
<span class="gp">></span>>> import ctypes
<span class="gp">></span>>> ctypes.string_at<span class="o">(</span><span class="m">0</span><span class="o">)</span>
<span class="go">Fatal Python error: Segmentation fault</span>
<span class="go">Current thread 0x00007fb899f39700 (most recent call first):</span>
<span class="go"> File "/home/python/cpython/Lib/ctypes/__init__.py", line 486 in string_at</span>
<span class="go"> File "<stdin>", line 1 in <module></span>
<span class="go">Segmentation fault</span>
</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="#"><code class="xref py py-mod docutils literal notranslate"><span class="pre">faulthandler</span></code> — Dump the Python traceback</a><ul>
<li><a class="reference internal" href="#dumping-the-traceback">Dumping the traceback</a></li>
<li><a class="reference internal" href="#fault-handler-state">Fault handler state</a></li>
<li><a class="reference internal" href="#dumping-the-tracebacks-after-a-timeout">Dumping the tracebacks after a timeout</a></li>
<li><a class="reference internal" href="#dumping-the-traceback-on-a-user-signal">Dumping the traceback on a user signal</a></li>
<li><a class="reference internal" href="#issue-with-file-descriptors">Issue with file descriptors</a></li>
<li><a class="reference internal" href="#example">Example</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="bdb.html"
title="previous chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">bdb</span></code> — Debugger framework</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="pdb.html"
title="next chapter"><code class="xref py py-mod docutils literal notranslate"><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="https://github.com/python/cpython/blob/3.7/Doc/library/faulthandler.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="pdb.html" title="pdb — The Python Debugger"
>next</a> |</li>
<li class="right" >
<a href="bdb.html" title="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>
<a href="../index.html">3.7.10 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" >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-2021, 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 Feb 26, 2021.
<a href="../bugs.html">Found a bug</a>?
<br />
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 2.3.1.
</div>
</body>
</html>
