19 Diagnostics library [diagnostics]

19.7 Debugging [debugging]

19.7.1 General [debugging.general]

1
#
Subclause [debugging] describes functionality to introspect and interact with the execution of the program.
[Note 1: 
The facilities provided by the debugging functionality interact with a program that could be tracing the execution of a C++ program, such as a debugger.
— end note]

19.7.2 Header <debugging> synopsis [debugging.syn]

🔗
// all freestanding namespace std { // [debugging.utility], utility void breakpoint() noexcept; void breakpoint_if_debugging() noexcept; bool is_debugger_present() noexcept; }

19.7.3 Utility [debugging.utility]

🔗
void breakpoint() noexcept;
1
#
The semantics of this function are implementation-defined.
[Note 1: 
It is intended that, when invoked with a debugger present, the execution of the program temporarily halts and execution is handed to the debugger until the program is either terminated by the debugger or the debugger resumes execution of the program as if the function was not invoked.
In particular, there is no intent for a call to this function to accomodate resumption of the program in a different manner.
If there is no debugger present, execution of the program can end abnormally.
— end note]
🔗
void breakpoint_if_debugging() noexcept;
2
#
Effects: Equivalent to: if (is_debugger_present()) breakpoint();
🔗
bool is_debugger_present() noexcept;
3
#
Required behavior: This function has no preconditions.
4
#
Default behavior: implementation-defined.
[Note 2: 
It is intended that, using an immediate (uncached) query to determine if the program is being traced by a debugger, an implementation returns true only when tracing the execution of the program with a debugger.
On Windows or equivalent systems, this can be achieved by calling the ​::​IsDebuggerPresent() Win32 function.
For systems compatible with ISO/IEC 23360:2021, this can be achieved by checking for a tracing process, with a best-effort determination that such a tracing process is a debugger.
— end note]
5
#
Remarks: This function is replaceable ([dcl.fct.def.replace]).