<!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 v3.3.2 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.3.2',
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 v3.3.2 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 v3.3.2 documentation" href="../index.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>
</head>
<body>
<div class="related">
<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="http://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">3.3.2 Documentation</a> »
</li>
<li><a href="index.html" >The Python Standard Library</a> »</li>
<li><a href="debug.html" accesskey="U">27. Debugging and Profiling</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<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."><tt class="xref py py-mod docutils literal"><span class="pre">faulthandler</span></tt></a> — Dump the Python traceback<a class="headerlink" href="#module-faulthandler" title="Permalink to this headline">¶</a></h1>
<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"><tt class="xref py py-func docutils literal"><span class="pre">faulthandler.enable()</span></tt></a> to
install fault handlers for the <tt class="xref py py-const docutils literal"><span class="pre">SIGSEGV</span></tt>, <tt class="xref py py-const docutils literal"><span class="pre">SIGFPE</span></tt>,
<tt class="xref py py-const docutils literal"><span class="pre">SIGABRT</span></tt>, <tt class="xref py py-const docutils literal"><span class="pre">SIGBUS</span></tt>, and <tt class="xref py py-const docutils literal"><span class="pre">SIGILL</span></tt> 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"><tt class="xref std std-envvar docutils literal"><span class="pre">PYTHONFAULTHANDLER</span></tt></a> environment
variable or by using <a class="reference internal" href="../using/cmdline.html#cmdoption-X"><em class="xref std std-option">-X</em></a> <tt class="docutils literal"><span class="pre">faulthandler</span></tt> 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 <tt class="xref c c-func docutils literal"><span class="pre">sigaltstack()</span></tt> 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 <tt class="docutils literal"><span class="pre">backslashreplace</span></tt> 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>
</ul>
<p>By default, the Python traceback is written to <a class="reference internal" href="sys.html#sys.stderr" title="sys.stderr"><tt class="xref py py-data docutils literal"><span class="pre">sys.stderr</span></tt></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"><tt class="xref py py-func docutils literal"><span class="pre">faulthandler.enable()</span></tt></a>.</p>
<p>The module is implemented in C, so tracebacks can be dumped on a crash or when
Python is deadlocked.</p>
<p class="versionadded">
<span class="versionmodified">New in version 3.3.</span> </p>
<div class="section" id="dump-the-traceback">
<h2>27.2.1. Dump the traceback<a class="headerlink" href="#dump-the-traceback" title="Permalink to this headline">¶</a></h2>
<dl class="function">
<dt id="faulthandler.dump_traceback">
<tt class="descclassname">faulthandler.</tt><tt class="descname">dump_traceback</tt><big>(</big><em>file=sys.stderr</em>, <em>all_threads=True</em><big>)</big><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
<tt class="xref docutils literal"><span class="pre">False</span></tt>, dump only the current thread.</p>
</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">
<tt class="descclassname">faulthandler.</tt><tt class="descname">enable</tt><big>(</big><em>file=sys.stderr</em>, <em>all_threads=True</em><big>)</big><a class="headerlink" href="#faulthandler.enable" title="Permalink to this definition">¶</a></dt>
<dd><p>Enable the fault handler: install handlers for the <tt class="xref py py-const docutils literal"><span class="pre">SIGSEGV</span></tt>,
<tt class="xref py py-const docutils literal"><span class="pre">SIGFPE</span></tt>, <tt class="xref py py-const docutils literal"><span class="pre">SIGABRT</span></tt>, <tt class="xref py py-const docutils literal"><span class="pre">SIGBUS</span></tt> and <tt class="xref py py-const docutils literal"><span class="pre">SIGILL</span></tt>
signals to dump the Python traceback. If <em>all_threads</em> is <tt class="xref docutils literal"><span class="pre">True</span></tt>,
produce tracebacks for every running thread. Otherwise, dump only the current
thread.</p>
</dd></dl>
<dl class="function">
<dt id="faulthandler.disable">
<tt class="descclassname">faulthandler.</tt><tt class="descname">disable</tt><big>(</big><big>)</big><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"><tt class="xref py py-func docutils literal"><span class="pre">enable()</span></tt></a>.</p>
</dd></dl>
<dl class="function">
<dt id="faulthandler.is_enabled">
<tt class="descclassname">faulthandler.</tt><tt class="descname">is_enabled</tt><big>(</big><big>)</big><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="dump-the-tracebacks-after-a-timeout">
<h2>27.2.3. Dump the tracebacks after a timeout<a class="headerlink" href="#dump-the-tracebacks-after-a-timeout" title="Permalink to this headline">¶</a></h2>
<dl class="function">
<dt id="faulthandler.dump_traceback_later">
<tt class="descclassname">faulthandler.</tt><tt class="descname">dump_traceback_later</tt><big>(</big><em>timeout</em>, <em>repeat=False</em>, <em>file=sys.stderr</em>, <em>exit=False</em><big>)</big><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 <tt class="xref docutils literal"><span class="pre">True</span></tt>. If <em>exit</em> is <tt class="xref docutils literal"><span class="pre">True</span></tt>, call
<tt class="xref c c-func docutils literal"><span class="pre">_exit()</span></tt> with status=1 after dumping the tracebacks. (Note
<tt class="xref c c-func docutils literal"><span class="pre">_exit()</span></tt> 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>This function is implemented using a watchdog thread and therefore is not
available if Python is compiled with threads disabled.</p>
</dd></dl>
<dl class="function">
<dt id="faulthandler.cancel_dump_traceback_later">
<tt class="descclassname">faulthandler.</tt><tt class="descname">cancel_dump_traceback_later</tt><big>(</big><big>)</big><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"><tt class="xref py py-func docutils literal"><span class="pre">dump_traceback_later()</span></tt></a>.</p>
</dd></dl>
</div>
<div class="section" id="dump-the-traceback-on-a-user-signal">
<h2>27.2.4. Dump the traceback on a user signal<a class="headerlink" href="#dump-the-traceback-on-a-user-signal" title="Permalink to this headline">¶</a></h2>
<dl class="function">
<dt id="faulthandler.register">
<tt class="descclassname">faulthandler.</tt><tt class="descname">register</tt><big>(</big><em>signum</em>, <em>file=sys.stderr</em>, <em>all_threads=True</em>, <em>chain=False</em><big>)</big><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
<tt class="xref docutils literal"><span class="pre">False</span></tt>, into <em>file</em>. Call the previous handler if chain is <tt class="xref docutils literal"><span class="pre">True</span></tt>.</p>
<p>Not available on Windows.</p>
</dd></dl>
<dl class="function">
<dt id="faulthandler.unregister">
<tt class="descclassname">faulthandler.</tt><tt class="descname">unregister</tt><big>(</big><em>signum</em><big>)</big><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"><tt class="xref py py-func docutils literal"><span class="pre">register()</span></tt></a>. Return <tt class="xref docutils literal"><span class="pre">True</span></tt> if the signal was registered,
<tt class="xref docutils literal"><span class="pre">False</span></tt> otherwise.</p>
<p>Not available on Windows.</p>
</dd></dl>
</div>
<div class="section" id="file-descriptor-issue">
<h2>27.2.5. File descriptor issue<a class="headerlink" href="#file-descriptor-issue" title="Permalink to this headline">¶</a></h2>
<p><a class="reference internal" href="#faulthandler.enable" title="faulthandler.enable"><tt class="xref py py-func docutils literal"><span class="pre">enable()</span></tt></a>, <a class="reference internal" href="#faulthandler.dump_traceback_later" title="faulthandler.dump_traceback_later"><tt class="xref py py-func docutils literal"><span class="pre">dump_traceback_later()</span></tt></a> and <a class="reference internal" href="#faulthandler.register" title="faulthandler.register"><tt class="xref py py-func docutils literal"><span class="pre">register()</span></tt></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"><tt class="xref py py-func docutils literal"><span class="pre">os.dup2()</span></tt></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:</p>
<div class="highlight-python3"><pre>$ python -q -X faulthandler
>>> import ctypes
>>> ctypes.string_at(0)
Fatal Python error: Segmentation fault
Current thread 0x00007fb899f39700:
File "/home/python/cpython/Lib/ctypes/__init__.py", line 486 in string_at
File "<stdin>", line 1 in <module>
Segmentation fault</pre>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper">
<h3><a href="../contents.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">27.2. <tt class="docutils literal"><span class="pre">faulthandler</span></tt> — Dump the Python traceback</a><ul>
<li><a class="reference internal" href="#dump-the-traceback">27.2.1. Dump 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="#dump-the-tracebacks-after-a-timeout">27.2.3. Dump the tracebacks after a timeout</a></li>
<li><a class="reference internal" href="#dump-the-traceback-on-a-user-signal">27.2.4. Dump the traceback on a user signal</a></li>
<li><a class="reference internal" href="#file-descriptor-issue">27.2.5. File descriptor issue</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. <tt class="docutils literal docutils literal docutils literal"><span class="pre">bdb</span></tt> — Debugger framework</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="pdb.html"
title="next chapter">27.3. <tt class="docutils literal"><span class="pre">pdb</span></tt> — The Python Debugger</a></p>
<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 id="searchbox" style="display: none">
<h3>Quick search</h3>
<form class="search" action="../search.html" method="get">
<input type="text" name="q" size="18" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
<p class="searchtip" style="font-size: 90%">
Enter search terms or a module, class or function name.
</p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related">
<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="http://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">3.3.2 Documentation</a> »
</li>
<li><a href="index.html" >The Python Standard Library</a> »</li>
<li><a href="debug.html" >27. Debugging and Profiling</a> »</li>
</ul>
</div>
<div class="footer">
© <a href="../copyright.html">Copyright</a> 1990-2013, Python Software Foundation.
<br />
The Python Software Foundation is a non-profit corporation.
<a href="http://www.python.org/psf/donations/">Please donate.</a>
<br />
Last updated on May 15, 2013.
<a href="../bugs.html">Found a bug</a>?
<br />
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.7.
</div>
</body>
</html>
