# Debugging Python crashes

If `cysignals` is imported, it sets up a hook which triggers when Python crashes. For example, it would be triggered on a segmentation fault outside a `sig_on()` block.

When a crash happens, first a simple C backtrace is printed if supported by the C library on the system. Then GDB is run to print a much more complete backtrace (except on OS X, where running a debugger requires special privileges). For your convenience, these GDB backtraces are also saved to a logfile.

Finally, this familiar message is shown:

    This probably occurred because a *compiled* module has a bug
    in it and is not properly wrapped with sig_on(), sig_off().
    Python will now terminate.

## Environment variables

There are several environment variables which influence this:

CYSIGNALS_CRASH_QUIET

  If set, be completely quiet whenever a crash happens. No backtrace or other message is shown and GDB is not run.

CYSIGNALS_CRASH_NDEBUG

  If set, disable the GDB backtrace. The simple backtrace is still shown.

CYSIGNALS_CRASH_LOGS

  The directory where the logs of the crashes are stored. If this is empty, disable storing of crash logs. The default is `cysignals_crash_logs` in the current directory.

CYSIGNALS_CRASH_DAYS

  Automatically delete crash logs older than this many days in the directory where crash logs are stored. A negative value means that logs are never deleted. The default is 7 days if `CYSIGNALS_CRASH_LOGS` is unset and -1 days (never delete) otherwise.