diff --git a/trap.h b/trap.h index 04cd33e2..40c60cea 100644 --- a/trap.h +++ b/trap.h @@ -105,26 +105,32 @@ NAMESPACE_BEGIN(CryptoPP) #if (CRYPTOPP_DEBUG && defined(UNIX_SIGNALS_AVAILABLE)) || defined(CRYPTOPP_DOXYGEN_PROCESSING) /// \brief Default SIGTRAP handler -/// \details 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. -/// \details 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. -/// \details 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 +/// \details 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. +/// \details 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. +/// \details 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. -/// \details If you want to ensure CRYPTOPP_ASSERT is inert, then do not define -/// CRYPTOPP_DEBUG, DEBUG or _DEBUG. Avoiding the defines means CRYPTOPP_ASSERT +/// \details 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)(exp)). -/// \details The traditional Posix define NDEBUG has no effect on CRYPTOPP_DEBUG, CRYPTOPP_ASSERT -/// or DebugTrapHandler. -/// \details An example of using \ref CRYPTOPP_ASSERT "CRYPTOPP_ASSERT" and DebugTrapHandler is shown below. The library's -/// test program, cryptest.exe (from test.cpp), exercises the structure: +/// \details The traditional Posix define NDEBUG has no effect on +/// CRYPTOPP_DEBUG, CRYPTOPP_ASSERT or DebugTrapHandler. +/// \details An example of using \ref CRYPTOPP_ASSERT "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)
 ///    static const DebugTrapHandler g_dummyHandler;
@@ -137,7 +143,8 @@ NAMESPACE_BEGIN(CryptoPP)
 ///    }
 ///
/// \since Crypto++ 5.6.5 -/// \sa \ref CRYPTOPP_ASSERT "CRYPTOPP_ASSERT", SignalHandler, Issue 277, +/// \sa \ref CRYPTOPP_ASSERT "CRYPTOPP_ASSERT", SignalHandler, Issue 277, /// CVE-2016-7420 #if defined(CRYPTOPP_DOXYGEN_PROCESSING)