uTools-Manuals/docs/python/faulthandler.html

<div class="body" role="main"><div class="section" id="module-faulthandler"><h1><span class="yiyi-st" id="yiyi-10">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> — 转储Python回溯</span></h1><div class="versionadded"><p><span class="yiyi-st" id="yiyi-11"><span class="versionmodified">版本3.3中的新功能。</span></span></p></div><p><span class="yiyi-st" id="yiyi-12">该模块包含在 段错误、超时或接收到用户信号之后显式转储Python 调用栈的功能。</span><span class="yiyi-st" id="yiyi-13">调用<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>为<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>和<code class="xref py py-const docutils literal"><span class="pre">SIGILL</span></code>信号。</span><span class="yiyi-st" id="yiyi-14">您也可以在启动时通过设置<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>环境变量或使用<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>命令行选项。</span></p><p><span class="yiyi-st" id="yiyi-15">故障处理程序与系统故障处理程序（如Apport或Windows故障处理程序）兼容。</span><span class="yiyi-st" id="yiyi-16">如果<code class="xref c c-func docutils literal"><span class="pre">sigaltstack()</span></code>函数可用，则模块使用替代堆栈用于信号处理程序。</span><span class="yiyi-st" id="yiyi-17">这允许它转储跟踪甚至在堆栈溢出。</span></p><p><span class="yiyi-st" id="yiyi-18">故障处理器在灾难性情况下被调用，因此只能使用信号安全功能（例如，</span><span class="yiyi-st" id="yiyi-19">它不能在堆上分配内存）。</span><span class="yiyi-st" id="yiyi-20">由于这个限制，与正常的Python跟踪相比，跟踪回复转储是最小的：</span></p><ul class="simple"><li><span class="yiyi-st" id="yiyi-21">仅支持ASCII。</span><span class="yiyi-st" id="yiyi-22">对编码使用<code class="docutils literal"><span class="pre">backslashreplace</span></code>错误处理程序。</span></li><li><span class="yiyi-st" id="yiyi-23">每个字符串限制为500个字符。</span></li><li><span class="yiyi-st" id="yiyi-24">仅显示文件名，功能名称和行​​号。</span><span class="yiyi-st" id="yiyi-25">（无源代码）</span></li><li><span class="yiyi-st" id="yiyi-26">它限制为100帧和100线程。</span></li><li><span class="yiyi-st" id="yiyi-27">顺序相反：最近的呼叫首先显示。</span></li></ul><p><span class="yiyi-st" id="yiyi-28">默认情况下，Python跟踪回写被写入到<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>。</span><span class="yiyi-st" id="yiyi-29">要查看回溯，应用程序必须在终端中运行。</span><span class="yiyi-st" id="yiyi-30">可以将日志文件传递给<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>。</span></p><p><span class="yiyi-st" id="yiyi-31">该模块在C中实现，因此traceback可以转储崩溃或当Python死锁。</span></p><div class="section" id="dumping-the-traceback"><h2><span class="yiyi-st" id="yiyi-32">27.2.1. </span><span class="yiyi-st" id="yiyi-33">转储回溯</span></h2><dl class="function"><dt id="faulthandler.dump_traceback"><span class="yiyi-st" id="yiyi-34"> <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></span></dt><dd><p><span class="yiyi-st" id="yiyi-35">将所有线程的追踪转储到<em>文件</em>中。</span><span class="yiyi-st" id="yiyi-36">如果<em>all_threads</em>为<code class="docutils literal"><span class="pre">False</span></code>，则只转储当前线程。</span></p><div class="versionchanged"><p><span class="yiyi-st" id="yiyi-37"><span class="versionmodified">在版本3.5中已更改：</span>添加了将文件描述器传递到此函数的支持。</span></p></div></dd></dl></div><div class="section" id="fault-handler-state"><h2><span class="yiyi-st" id="yiyi-38">27.2.2. </span><span class="yiyi-st" id="yiyi-39">错误处理程序状态</span></h2><dl class="function"><dt id="faulthandler.enable"><span class="yiyi-st" id="yiyi-40"> <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></span></dt><dd><p><span class="yiyi-st" id="yiyi-41">启用故障处理程序：安装<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>和<code class="xref py py-const docutils literal"><span class="pre">SIGILL</span></code></span><span class="yiyi-st" id="yiyi-42">如果<em>all_threads</em>为<code class="docutils literal"><span class="pre">True</span></code>，则为每个正在运行的线程产生追溯。</span><span class="yiyi-st" id="yiyi-43">否则，只转储当前线程。</span></p><p><span class="yiyi-st" id="yiyi-44"><em>文件</em>必须保持打开，直到故障处理程序被禁用：参见<a class="reference internal" href="#faulthandler-fd"><span>issue with file descriptors</span></a>。</span></p><div class="versionchanged"><p><span class="yiyi-st" id="yiyi-45"><span class="versionmodified">在版本3.5中已更改：</span>添加了将文件描述器传递到此函数的支持。</span></p></div></dd></dl><dl class="function"><dt id="faulthandler.disable"><span class="yiyi-st" id="yiyi-46"> <code class="descclassname">faulthandler.</code><code class="descname">disable</code><span class="sig-paren">(</span><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-47">禁用故障处理程序：卸载由<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>安装的信号处理程序。</span></p></dd></dl><dl class="function"><dt id="faulthandler.is_enabled"><span class="yiyi-st" id="yiyi-48"> <code class="descclassname">faulthandler.</code><code class="descname">is_enabled</code><span class="sig-paren">(</span><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-49">检查故障处理程序是否已启用。</span></p></dd></dl></div><div class="section" id="dumping-the-tracebacks-after-a-timeout"><h2><span class="yiyi-st" id="yiyi-50">27.2.3. </span><span class="yiyi-st" id="yiyi-51">在超时后转储追溯</span></h2><dl class="function"><dt id="faulthandler.dump_traceback_later"><span class="yiyi-st" id="yiyi-52"> <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></span></dt><dd><p><span class="yiyi-st" id="yiyi-53">如果<em>重复</em>是<code class="docutils literal"><span class="pre">True</span></code>，则在超时<em>超时</em>秒或每个<em>超时</em> 。</span><span class="yiyi-st" id="yiyi-54">如果<em>退出</em>为<code class="docutils literal"><span class="pre">True</span></code>，则在转储跟踪后调用状态= 1的<code class="xref c c-func docutils literal"><span class="pre">_exit()</span></code>。</span><span class="yiyi-st" id="yiyi-55">（注意<code class="xref c c-func docutils literal"><span class="pre">_exit()</span></code>立即退出该过程，这意味着它不会执行任何清理，如刷新文件缓冲区。）</span><span class="yiyi-st" id="yiyi-56">如果函数被调用两次，新调用将替换以前的参数并重置超时。</span><span class="yiyi-st" id="yiyi-57">定时器具有亚秒分辨率。</span></p><p><span class="yiyi-st" id="yiyi-58"><em>文件</em>必须保持打开状态，直到调用traceback或调用<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>：请参阅<a class="reference internal" href="#faulthandler-fd"><span>issue with file descriptors</span></a>。</span></p><p><span class="yiyi-st" id="yiyi-59">此函数使用看门狗线程实现，因此如果Python编译时禁用线程，则不可用。</span></p><div class="versionchanged"><p><span class="yiyi-st" id="yiyi-60"><span class="versionmodified">在版本3.5中已更改：</span>添加了将文件描述器传递到此函数的支持。</span></p></div></dd></dl><dl class="function"><dt id="faulthandler.cancel_dump_traceback_later"><span class="yiyi-st" id="yiyi-61"> <code class="descclassname">faulthandler.</code><code class="descname">cancel_dump_traceback_later</code><span class="sig-paren">(</span><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-62">取消最后一次调用<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>。</span></p></dd></dl></div><div class="section" id="dumping-the-traceback-on-a-user-signal"><h2><span class="yiyi-st" id="yiyi-63">27.2.4. </span><span class="yiyi-st" id="yiyi-64">将追踪信息转储到用户信号上</span></h2><dl class="function"><dt id="faulthandler.register"><span class="yiyi-st" id="yiyi-65"> <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></span></dt><dd><p><span class="yiyi-st" id="yiyi-66">注册用户信号：为<em>signum</em>信号安装处理程序以转储所有线程或当前线程的跟踪（如果<em>all_threads</em>为<code class="docutils literal"><span class="pre">False</span></code> ，到<em>文件</em>。</span><span class="yiyi-st" id="yiyi-67">如果chain为<code class="docutils literal"><span class="pre">True</span></code>，则调用上一个处理程序。</span></p><p><span class="yiyi-st" id="yiyi-68"><em>文件</em>必须保持打开状态，直到<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>未注册信号：请参阅文件描述器中的<a class="reference internal" href="#faulthandler-fd"><span>issue with file descriptors</span></a></span></p><p><span class="yiyi-st" id="yiyi-69">在Windows上不可用。</span></p><div class="versionchanged"><p><span class="yiyi-st" id="yiyi-70"><span class="versionmodified">在版本3.5中已更改：</span>添加了将文件描述器传递到此函数的支持。</span></p></div></dd></dl><dl class="function"><dt id="faulthandler.unregister"><span class="yiyi-st" id="yiyi-71"> <code class="descclassname">faulthandler.</code><code class="descname">unregister</code><span class="sig-paren">(</span><em>signum</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-72">取消注册用户信号：卸载由<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>安装的<em>signum</em>信号处理程序。</span><span class="yiyi-st" id="yiyi-73">如果信号已注册，则返回<code class="docutils literal"><span class="pre">True</span></code>，否则返回<code class="docutils literal"><span class="pre">False</span></code>。</span></p><p><span class="yiyi-st" id="yiyi-74">在Windows上不可用。</span></p></dd></dl></div><div class="section" id="issue-with-file-descriptors"><h2><span class="yiyi-st" id="yiyi-75">27.2.5. </span><span class="yiyi-st" id="yiyi-76">问题与文件描述符</span></h2><p><span class="yiyi-st" id="yiyi-77"><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>和<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>保留其<em>文件</em>参数的文件描述器。</span><span class="yiyi-st" id="yiyi-78">如果文件关闭并且其文件描述器由一个新文件重用，或者如果<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>用于替换文件描述器，则该追溯将被写入另一个文件。</span><span class="yiyi-st" id="yiyi-79">每次更换文件时都调用这些函数。</span></p></div><div class="section" id="example"><h2><span class="yiyi-st" id="yiyi-80">27.2.6. </span><span class="yiyi-st" id="yiyi-81">示例</span></h2><p><span class="yiyi-st" id="yiyi-82">Linux上启用和未启用故障处理程序的分段故障示例：</span></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
&gt;&gt;&gt; import ctypes
&gt;&gt;&gt; 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">"&lt;stdin&gt;"</span>, line <span class="m">1</span> in &lt;module&gt;
Segmentation fault
</pre></div></div></div></div></div>