new repository

1 files changed, 50 insertions, 0 deletions

diff --git a/devdocs/python~3.12/library%2Ffaulthandler.html b/devdocs/python~3.12/library%2Ffaulthandler.html
new file mode 100644
index 00000000..2e8ce8ae
--- /dev/null
+++ b/devdocs/python~3.12/library%2Ffaulthandler.html
@@ -0,0 +1,50 @@
+ <span id="faulthandler-dump-the-python-traceback"></span><h1>faulthandler — Dump the Python traceback</h1> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.3.</span></p> </div>  <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>faulthandler.enable()</code></a> to install fault handlers for the <code>SIGSEGV</code>, <code>SIGFPE</code>, <code>SIGABRT</code>, <code>SIGBUS</code>, and <code>SIGILL</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#envvar-PYTHONFAULTHANDLER"><code>PYTHONFAULTHANDLER</code></a> environment variable or by using the <a class="reference internal" href="../using/cmdline#cmdoption-X"><code>-X</code></a> <code>faulthandler</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>sigaltstack()</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>backslashreplace</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#sys.stderr" title="sys.stderr"><code>sys.stderr</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>faulthandler.enable()</code></a>.</p> <p>The module is implemented in C, so tracebacks can be dumped on a crash or when Python is deadlocked.</p> <p>The <a class="reference internal" href="devmode#devmode"><span class="std std-ref">Python Development Mode</span></a> calls <a class="reference internal" href="#faulthandler.enable" title="faulthandler.enable"><code>faulthandler.enable()</code></a> at Python startup.</p> <div class="admonition seealso"> <p class="admonition-title">See also</p> <dl class="simple"> <dt>
+<code>Module</code> <a class="reference internal" href="pdb#module-pdb" title="pdb: The Python debugger for interactive interpreters."><code>pdb</code></a>
+</dt>
+<dd>
+<p>Interactive source code debugger for Python programs.</p> </dd> <dt>
+<code>Module</code> <a class="reference internal" href="traceback#module-traceback" title="traceback: Print or retrieve a stack traceback."><code>traceback</code></a>
+</dt>
+<dd>
+<p>Standard interface to extract, format and print stack traces of Python programs.</p> </dd> </dl> </div> <section id="dumping-the-traceback"> <h2>Dumping the traceback</h2> <dl class="py function"> <dt class="sig sig-object py" id="faulthandler.dump_traceback">
+<code>faulthandler.dump_traceback(file=sys.stderr, all_threads=True)</code> </dt> <dd>
+<p>Dump the tracebacks of all threads into <em>file</em>. If <em>all_threads</em> is <code>False</code>, dump only the current thread.</p> <div class="admonition seealso"> <p class="admonition-title">See also</p> <p><a class="reference internal" href="traceback#traceback.print_tb" title="traceback.print_tb"><code>traceback.print_tb()</code></a>, which can be used to print a traceback object.</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> </section> <section id="fault-handler-state"> <h2>Fault handler state</h2> <dl class="py function"> <dt class="sig sig-object py" id="faulthandler.enable">
+<code>faulthandler.enable(file=sys.stderr, all_threads=True)</code> </dt> <dd>
+<p>Enable the fault handler: install handlers for the <code>SIGSEGV</code>, <code>SIGFPE</code>, <code>SIGABRT</code>, <code>SIGBUS</code> and <code>SIGILL</code> signals to dump the Python traceback. If <em>all_threads</em> is <code>True</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> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.10: </span>The dump now mentions if a garbage collector collection is running if <em>all_threads</em> is true.</p> </div> </dd>
+</dl> <dl class="py function"> <dt class="sig sig-object py" id="faulthandler.disable">
+<code>faulthandler.disable()</code> </dt> <dd>
+<p>Disable the fault handler: uninstall the signal handlers installed by <a class="reference internal" href="#faulthandler.enable" title="faulthandler.enable"><code>enable()</code></a>.</p> </dd>
+</dl> <dl class="py function"> <dt class="sig sig-object py" id="faulthandler.is_enabled">
+<code>faulthandler.is_enabled()</code> </dt> <dd>
+<p>Check if the fault handler is enabled.</p> </dd>
+</dl> </section> <section id="dumping-the-tracebacks-after-a-timeout"> <h2>Dumping the tracebacks after a timeout</h2> <dl class="py function"> <dt class="sig sig-object py" id="faulthandler.dump_traceback_later">
+<code>faulthandler.dump_traceback_later(timeout, repeat=False, file=sys.stderr, exit=False)</code> </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>True</code>. If <em>exit</em> is <code>True</code>, call <code>_exit()</code> with status=1 after dumping the tracebacks. (Note <code>_exit()</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>cancel_dump_traceback_later()</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="py function"> <dt class="sig sig-object py" id="faulthandler.cancel_dump_traceback_later">
+<code>faulthandler.cancel_dump_traceback_later()</code> </dt> <dd>
+<p>Cancel the last call to <a class="reference internal" href="#faulthandler.dump_traceback_later" title="faulthandler.dump_traceback_later"><code>dump_traceback_later()</code></a>.</p> </dd>
+</dl> </section> <section id="dumping-the-traceback-on-a-user-signal"> <h2>Dumping the traceback on a user signal</h2> <dl class="py function"> <dt class="sig sig-object py" id="faulthandler.register">
+<code>faulthandler.register(signum, file=sys.stderr, all_threads=True, chain=False)</code> </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>False</code>, into <em>file</em>. Call the previous handler if chain is <code>True</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>unregister()</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="py function"> <dt class="sig sig-object py" id="faulthandler.unregister">
+<code>faulthandler.unregister(signum)</code> </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>register()</code></a>. Return <code>True</code> if the signal was registered, <code>False</code> otherwise.</p> <p>Not available on Windows.</p> </dd>
+</dl> </section> <section id="issue-with-file-descriptors"> <span id="faulthandler-fd"></span><h2>Issue with file descriptors</h2> <p><a class="reference internal" href="#faulthandler.enable" title="faulthandler.enable"><code>enable()</code></a>, <a class="reference internal" href="#faulthandler.dump_traceback_later" title="faulthandler.dump_traceback_later"><code>dump_traceback_later()</code></a> and <a class="reference internal" href="#faulthandler.register" title="faulthandler.register"><code>register()</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#os.dup2" title="os.dup2"><code>os.dup2()</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> </section> <section id="example"> <h2>Example</h2> <p>Example of a segmentation fault on Linux with and without enabling the fault handler:</p> <pre data-language="shell">$ python -c "import ctypes; ctypes.string_at(0)"
+Segmentation fault
+
+$ python -q -X faulthandler
+&gt;&gt;&gt; import ctypes
+&gt;&gt;&gt; ctypes.string_at(0)
+Fatal Python error: Segmentation fault
+
+Current thread 0x00007fb899f39700 (most recent call first):
+  File "/home/python/cpython/Lib/ctypes/__init__.py", line 486 in string_at
+  File "&lt;stdin&gt;", line 1 in &lt;module&gt;
+Segmentation fault
+</pre> </section> <div class="_attribution">
+  <p class="_attribution-p">
+    &copy; 2001&ndash;2023 Python Software Foundation<br>Licensed under the PSF License.<br>
+    <a href="https://docs.python.org/3.12/library/faulthandler.html" class="_attribution-link">https://docs.python.org/3.12/library/faulthandler.html</a>
+  </p>
+</div>