-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathfaulthandler.html
More file actions
347 lines (316 loc) · 23.2 KB
/
faulthandler.html
File metadata and controls
347 lines (316 loc) · 23.2 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
<!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" lang="zh_TW">
<head>
<meta http-equiv="X-UA-Compatible" content="IE=Edge" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>28.2. faulthandler — Dump the Python traceback — Python 3.7.0 說明文件</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/translations.js"></script>
<script type="text/javascript" src="../_static/sidebar.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="在 Python 3.7.0 說明文件 中搜尋"
href="../_static/opensearch.xml"/>
<link rel="author" title="關於這些文件" href="../about.html" />
<link rel="index" title="索引" href="../genindex.html" />
<link rel="search" title="搜尋" href="../search.html" />
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="next" title="28.3. pdb — The Python Debugger" href="pdb.html" />
<link rel="prev" title="28.1. 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>
<script type="text/javascript" src="../_static/switchers.js"></script>
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>瀏覽</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">索引</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python 模組索引"
>模組</a> |</li>
<li class="right" >
<a href="pdb.html" title="28.3. pdb — The Python Debugger"
accesskey="N">下一頁</a> |</li>
<li class="right" >
<a href="bdb.html" title="28.1. bdb — Debugger framework"
accesskey="P">上一頁</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">zh_TW</span>
<span class="version_switcher_placeholder">3.7.0</span>
<a href="../index.html">Documentation </a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python 標準函式庫 (Standard Library)</a> »</li>
<li class="nav-item nav-item-2"><a href="debug.html" accesskey="U">28. 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>28.2. <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="本標題的永久連結">¶</a></h1>
<div class="versionadded">
<p><span class="versionmodified">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>Only ASCII is supported. The <code class="docutils literal notranslate"><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 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>28.2.1. Dumping the traceback<a class="headerlink" href="#dumping-the-traceback" title="本標題的永久連結">¶</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="本定義的永久連結">¶</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">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>28.2.2. Fault handler state<a class="headerlink" href="#fault-handler-state" title="本標題的永久連結">¶</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="本定義的永久連結">¶</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">3.5 版更變: </span>Added support for passing file descriptor to this function.</p>
</div>
<div class="versionchanged">
<p><span class="versionmodified">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="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="本定義的永久連結">¶</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="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="本定義的永久連結">¶</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>28.2.3. Dumping the tracebacks after a timeout<a class="headerlink" href="#dumping-the-tracebacks-after-a-timeout" title="本標題的永久連結">¶</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="本定義的永久連結">¶</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 and therefore is not
available if Python is compiled with threads disabled.</p>
<div class="versionchanged">
<p><span class="versionmodified">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="本定義的永久連結">¶</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>28.2.4. Dumping the traceback on a user signal<a class="headerlink" href="#dumping-the-traceback-on-a-user-signal" title="本標題的永久連結">¶</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="本定義的永久連結">¶</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">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="本定義的永久連結">¶</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>28.2.5. Issue with file descriptors<a class="headerlink" href="#issue-with-file-descriptors" title="本標題的永久連結">¶</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>28.2.6. Example<a class="headerlink" href="#example" title="本標題的永久連結">¶</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">目錄</a></h3>
<ul>
<li><a class="reference internal" href="#">28.2. <code class="docutils literal notranslate"><span class="pre">faulthandler</span></code> — Dump the Python traceback</a><ul>
<li><a class="reference internal" href="#dumping-the-traceback">28.2.1. Dumping the traceback</a></li>
<li><a class="reference internal" href="#fault-handler-state">28.2.2. Fault handler state</a></li>
<li><a class="reference internal" href="#dumping-the-tracebacks-after-a-timeout">28.2.3. Dumping the tracebacks after a timeout</a></li>
<li><a class="reference internal" href="#dumping-the-traceback-on-a-user-signal">28.2.4. Dumping the traceback on a user signal</a></li>
<li><a class="reference internal" href="#issue-with-file-descriptors">28.2.5. Issue with file descriptors</a></li>
<li><a class="reference internal" href="#example">28.2.6. Example</a></li>
</ul>
</li>
</ul>
<h4>上個主題</h4>
<p class="topless"><a href="bdb.html"
title="上一章">28.1. <code class="docutils literal notranslate"><span class="pre">bdb</span></code> — Debugger framework</a></p>
<h4>下個主題</h4>
<p class="topless"><a href="pdb.html"
title="下一章">28.3. <code class="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>瀏覽</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>索引</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python 模組索引"
>模組</a> |</li>
<li class="right" >
<a href="pdb.html" title="28.3. pdb — The Python Debugger"
>下一頁</a> |</li>
<li class="right" >
<a href="bdb.html" title="28.1. bdb — Debugger framework"
>上一頁</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">zh_TW</span>
<span class="version_switcher_placeholder">3.7.0</span>
<a href="../index.html">Documentation </a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python 標準函式庫 (Standard Library)</a> »</li>
<li class="nav-item nav-item-2"><a href="debug.html" >28. 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-2018, 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 8月 22, 2018.
<a href="../bugs.html">Found a bug</a>?
<br />
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.7.7.
</div>
</body>
</html>