This repository has been archived by the owner on Apr 24, 2020. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 28
/
README
297 lines (221 loc) · 10.5 KB
/
README
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
+++++++++++++
Fault handler
+++++++++++++
Fault handler for SIGSEGV, SIGFPE, SIGABRT, SIGBUS and SIGILL signals: display
the Python traceback and restore the previous handler. Allocate an alternate
stack for this handler, if sigaltstack() is available, to be able to allocate
memory on the stack, even on stack overflow (not available on Windows).
Import the module and call faulthandler.enable() to enable the fault handler.
The fault handler is called on catastrophic cases and so it can only use
signal-safe functions (eg. it doesn't allocate memory on the heap). That's why
the traceback is limited: it only supports ASCII encoding (use the
backslashreplace error handler for non-ASCII characters) and limits each string
to 100 characters, doesn't print the source code in the traceback (only the
filename, the function name and the line number), is limited to 100 frames and
100 threads.
By default, the Python traceback is written to the standard error stream. Start
your graphical applications in a terminal and run your server in foreground to
see the traceback, or pass a file to faulthandler.enable().
faulthandler is implemented in C using signal handlers to be able to dump a
traceback on a crash or when Python is blocked (eg. deadlock).
Website:
https://github.com/haypo/faulthandler/wiki/
faulthandler is part of Python since Python 3.3:
http://docs.python.org/dev/library/faulthandler.html
Example
=======
Example of a segmentation fault on Linux: ::
$ python
>>> import faulthandler
>>> faulthandler.enable()
>>> faulthandler._sigsegv()
Fatal Python error: Segmentation fault
Traceback (most recent call first):
File "<stdin>", line 1 in <module>
Segmentation fault
Installation
============
To install faulthandler module, type the following command: ::
python setup.py install
Then you can test your setup using the following command: ::
python tests.py
You need a C compiler (eg. gcc) and Python headers to build the faulthandler
module. Eg. on Fedora, you have to install python-devel package (sudo yum
install python-devel).
faulthandler module API
=======================
There are 4 different ways to display the Python traceback:
* enable(): on a crash
* dump_tracebacks_later(): after a timeout (useful if your program hangs)
* register(): by sending a signal (eg. SIGUSR1). It doesn't work on Windows.
* dump_traceback(): explicitly
Fault handler state (disabled by default):
* enable(file=sys.stderr, all_threads=False): enable the fault handler
* disable(): disable the fault handler
* is_enabled(): get the status of the fault handler
Dump the current traceback:
* dump_traceback(file=sys.stderr, all_threads=False): dump traceback of the
current thread, or of all threads if all_threads is True, into file
* dump_tracebacks_later(timeout, repeat=False, file=sys.stderr,
exit=False): dump the traceback of all threads in timeout seconds, or each
timeout seconds if repeat is True. If the function is called twice, the new
call replaces previous parameters. Exit immediatly if exit is True.
* cancel_dump_tracebacks_later(): cancel the previous call to
dump_tracebacks_later()
dump_tracebacks_later() is implemented using the SIGALRM signal and the alarm()
function: if the signal handler is called during a system call, the system call
is interrupted (return EINTR). It it not available on Windows.
enable() and dump_tracebacks_later() keep an internal reference to the output
file. Use disable() and cancel_dump_tracebacks_later() to clear this reference.
Dump the traceback on an user signal:
* register(signum, file=sys.stderr, all_threads=False): register an handler
for the signal 'signum': dump the traceback of the current thread, or of all
threads if all_threads is True, into file". Not available on Windows.
* unregister(signum): unregister the handler of the signal 'signum' registered
by register(). Not available on Windows.
Functions to test the fault handler:
* _fatal_error(message): Exit Python with a fatal error, call Py_FatalError()
with message.
* _read_null(): read from the NULL pointer (raise SIGSEGV or SIGBUS depending
on the platform)
* _sigabrt(): raise a SIGABRT signal (Aborted)
* _sigbus(): raise a SIGBUS signal (Bus error)
* _sigfpe(): raise a SIGFPE signal (Floating point exception), do a division by
zero
* _sigill(): raise a SIGILL signal (Illegal instruction)
* _sigsegv(): raise a SIGSEGV signal (Segmentation fault), read memory from
NULL (address 0)
* _stack_overflow(): raise a stack overflow error. Not available on all
platforms.
register(), unregister(), sigbus() and sigill() are not available on all
operation systems.
faulthandler.version_info is the module version as a tuple: (major, minor),
faulthandler.__version__ is the module version as a string (e.g. "2.0").
Changelog
=========
Version 2.1 (under development)
-------------------------------
Major changes:
* Add an optional chain argument to faulthandler.register()
Version 2.0 (2011-05-10)
------------------------
Major changes:
* faulthandler is now part of Python 3.3
* enable() handles also the SIGABRT signal
* Add exit option to dump_tracebacks_later(): if True, exit the program
on timeout after dumping the traceback
Other changes:
* Change default value of the all_threads argument: dump all threads by
default because under some rare conditions, it is not possible to get
the current thread
* Save/restore errno in signal handlers
* dump_tracebacks_later() always dump all threads: remove all_threads option
* Add faulthandler.__version__ attribute (module version as a string)
* faulthandler.version is now a tuple
* Rename:
* dump_traceback_later() to dump_tracebacks_later()
* cancel_dump_traceback_later() to cancel_dump_tracebacks_later()
* sigsegv() to _sigsegv()
* sigfpe() to _sigfpe()
* sigbus() to _sigbus()
* sigill() to _sigill()
* register() and unregister() are no more available on Windows. They were
useless: only SIGSEGV, SIGABRT and SIGILL can be handled by the application,
and these signals can only be handled by enable().
* Add _fatal_error(), _read_null(), _sigabrt() and _stack_overflow() test
functions
* register() uses sigaction() SA_RESTART flag to try to not interrupt the
current system call
* The fault handler calls the previous signal handler, using sigaction()
SA_NODEFER flag to call it immediatly
* enable() raises an OSError if it was not possible to register a signal
handler
* Set module size to 0, instead of -1, to be able to unload the module with
Python 3
* Fix a reference leak in dump_tracebacks_later()
* Fix register() if it called twice with the same signal
* Implement m_traverse for Python 3 to help the garbage collector
* Move code from faulthandler/\*.c to faulthandler.c and traceback.c: the code
is simpler and it was easier to integrate faulthandler into Python 3.3 using
one file (traceback.c already existed in Python)
* register() uses a static list for all signals instead of reallocating memory
each time a new signal is registered, because the list is shared with the
signal handler which may be called anytime.
Version 1.5 (2011-03-24)
------------------------
* Conform to the PEP 8:
* Rename isenabled() to is_enabled()
* Rename dumpbacktrace() to dump_traceback()
* Rename dumpbacktrace_later() to dump_traceback_later()
* Rename cancel_dumpbacktrace_later() to cancel_dump_traceback_later()
* Limit strings to 100 characters
* dump_traceback_later() signal handler doesn't clear its reference to the
file, because Py_CLEAR() is not signal safe: you have to call explicitly
cancel_dump_traceback_later()
Version 1.4 (2011-02-14)
------------------------
* Add register() and unregister() functions
* Add optional all_threads argument to enable()
* Limit the backtrace to 100 threads
* Allocate an alternative stack for the fatal signal handler to be able to
display a backtrace on a stack overflow (define HAVE_SIGALTSTACK). Not
available on Windows.
Version 1.3 (2011-01-31)
------------------------
* Don't compile dumpbacktrace_later() and cancel_dumpbacktrace_later() on
Windows because alarm() is missing
Version 1.2 (2011-01-31)
------------------------
* Add dumpbacktrace_later() and cancel_dumpbacktrace_later() function
* enable() and dumpbacktrace() get an optional file argument
* Replace dumpbacktrace_threads() function by a new dumpbacktrace() argument:
dumpbacktrace(all_threads=True)
* enable() gets the file descriptor of sys.stderr instead of using the file
descriptor 2
Version 1.1 (2011-01-03)
------------------------
* Disable the handler by default, because pkgutil may load the module and so
enable the handler which is unexpected
* Add dumpbacktrace() and dumpbacktrace_threads() functions
* sigill() is available on Windows thanks to Martin's patch
* Fix dump_ascii() for signed char type (eg. on FreeBSD)
* Fix tests.py for Python 2.5
Version 1.0 (2010-12-24)
------------------------
* First public release
Status
======
* 2011-01-31: Version 1.2 tested with Python 2.5, 2.6, 2.7, 3.1 and 3.2 on
Debian Sid
* 2010-12-24: Tested with Python 2.6, 3.1 and 3.2 on Debian Sid
* 2010-12-24: Tested with Python 2.6 and 3.1 on Windows XP
Similar projects
================
Python debuggers:
* minidumper is a C extension for writing "minidumps" for post-mortem analysis
of crashes in Python or its extensions:
https://bitbucket.org/briancurtin/minidumper/
* tipper: write the traceback of the current thread into a file on SIGUSR1
signal: http://pypi.python.org/pypi/tipper/
* crier: write the traceback of the current thread into a file
(eg. /tmp/dump-<pid>) if a "request" file is created (eg. /tmp/crier-<pid>).
Implemented using a thread. https://gist.github.com/737056
* Python WAD (Wrapped Application Debugger), not update since 2001:
http://www.dabeaz.com/papers/Python2001/python.html
Application fault handlers:
* The GNU libc has a fault handler in debug/segfault.c
* XEmacs has a fault handler displaying the Lisp traceback
* RPy has a fault handler
System-wide fault handlers:
* Ubuntu uses Apport: https://wiki.ubuntu.com/Apport
* The Linux kernel logs also segfaults into /var/log/kern.log (and
/var/log/syslog). /proc/sys/kernel/core_pattern contols how coredumps are
created.
* Windows opens a popup on a fatal error asking if the error should be
reported to Microsoft
See also
========
* http://bugs.python.org/issue8863 (may 2010):
Display Python backtrace on SIGSEGV, SIGFPE and fatal error
* http://bugs.python.org/issue3999 (sept. 2008):
Real segmentation fault handler