Init

cppdraft/debugging.md

@@ -0,0 +1,104 @@
+[debugging]
+
+# 19 Diagnostics library [[diagnostics]](./#diagnostics)
+
+## 19.7 Debugging [debugging]
+
+### [19.7.1](#general) General [[debugging.general]](debugging.general)
+
+[1](#general-1)
+
+[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/diagnostics.tex#L2413)
+
+Subclause [debugging] describes functionality to introspect and
+interact with the execution of the program[.](#general-1.sentence-1)
+
+[*Note [1](#general-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[.](#general-1.sentence-2)
+
+— *end note*]
+
+### [19.7.2](#syn) Header <debugging> synopsis [[debugging.syn]](debugging.syn)
+
+[🔗](#header:%3cdebugging%3e)
+
+// all freestandingnamespace std {// [[debugging.utility]](#utility "19.7.3 Utility"), utilityvoid breakpoint() noexcept; void breakpoint_if_debugging() noexcept; bool is_debugger_present() noexcept;}
+
+### [19.7.3](#utility) Utility [[debugging.utility]](debugging.utility)
+
+[🔗](#lib:breakpoint)
+
+`void breakpoint() noexcept;
+`
+
+[1](#utility-1)
+
+[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/diagnostics.tex#L2444)
+
+The semantics of this function are implementation-defined[.](#utility-1.sentence-1)
+
+[*Note [1](#utility-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[.](#utility-1.sentence-2)
+
+In particular, there is no
+intent for a call to this function to accomodate resumption of the program in a
+different manner[.](#utility-1.sentence-3)
+
+If there is no debugger present, execution of the program can
+end abnormally[.](#utility-1.sentence-4)
+
+— *end note*]
+
+[🔗](#lib:breakpoint_if_debugging)
+
+`void breakpoint_if_debugging() noexcept;
+`
+
+[2](#utility-2)
+
+[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/diagnostics.tex#L2466)
+
+*Effects*: Equivalent to:if (is_debugger_present()) breakpoint();
+
+[🔗](#lib:is_debugger_present)
+
+`bool is_debugger_present() noexcept;
+`
+
+[3](#utility-3)
+
+[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/diagnostics.tex#L2481)
+
+*Required behavior*: This function has no preconditions[.](#utility-3.sentence-1)
+
+[4](#utility-4)
+
+[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/diagnostics.tex#L2485)
+
+*Default behavior*: implementation-defined[.](#utility-4.sentence-1)
+
+[*Note [2](#utility-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[.](#utility-4.sentence-2)
+
+On Windows or
+equivalent systems, this can be achieved by calling the​::​IsDebuggerPresent() Win32 function[.](#utility-4.sentence-3)
+
+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[.](#utility-4.sentence-4)
+
+— *end note*]
+
+[5](#utility-5)
+
+[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/diagnostics.tex#L2499)
+
+*Remarks*: This function is replaceable ([[dcl.fct.def.replace]](dcl.fct.def.replace#term.replaceable.function "9.6.5 Replaceable function definitions"))[.](#utility-5.sentence-1)