DebugTrapHandler Class Reference

Default SIGTRAP handler. More...

`#include <trap.h>`

Inheritance diagram for DebugTrapHandler:

## Additional Inherited Members

Public Member Functions inherited from SignalHandler< SIGTRAP, false >
| SignalHandler (SignalHandlerFn pfn=NULL, int flags=0)
| Construct a signal handler.

## Detailed Description

Default SIGTRAP handler.

DebugTrapHandler() can be used by a program to install an empty SIGTRAP handler. If present, the handler ensures there is a signal handler in place for `SIGTRAP` raised by `CRYPTOPP_ASSERT`. If `CRYPTOPP_ASSERT` raises `SIGTRAP` without a handler, then one of two things can occur. First, the OS might allow the program to continue. Second, the OS might terminate the program. OS X allows the program to continue, while some Linuxes terminate the program.

If DebugTrapHandler detects another handler in place, then it will not install a handler. This ensures a debugger can gain control of the `SIGTRAP` signal without contention. It also allows multiple DebugTrapHandler to be created without contentious or unusual behavior. Though multiple DebugTrapHandler can be created, a program should only create one, if needed.

A DebugTrapHandler is subject to C++ static initialization [dis]order. If you need to install a handler and it must be installed early, then reference the code associated with `CRYPTOPP_INIT_PRIORITY` in cryptlib.cpp and cpu.cpp.

If you want to ensure `CRYPTOPP_ASSERT` is inert, then do not define `CRYPTOPP_DEBUG`, `DEBUG` or `_DEBUG`. Avoiding the defines means `CRYPTOPP_ASSERT` is processed into `((void)0)`.

The traditional Posix define `NDEBUG` has no effect on `CRYPTOPP_DEBUG`, `CRYPTOPP_ASSERT` or DebugTrapHandler.

An example of using CRYPTOPP_ASSERT and DebugTrapHandler is shown below. The library's test program, `cryptest.exe` (from test.cpp), exercises the structure:

      #if defined(CRYPTOPP_DEBUG) && defined(UNIX_SIGNALS_AVAILABLE)
      const DebugTrapHandler g_dummyHandler;
      #endif

      int main(int argc, char* argv[])
      {
         CRYPTOPP_ASSERT(argv != nullptr);
         ...
      }

Since
  Crypto++ 5.6.5

See also
  CRYPTOPP_ASSERT, SignalHandler, Issue 277, CVE-2016-7420

Definition at line 154 of file trap.h.

The documentation for this class was generated from the following file:

- trap.h