deploy openssl/openssl@5174da4 to 3.1

3.1/man3/OSSL_trace_enabled/index.html

@@ -37,7 +37,7 @@
 if (OSSL_TRACE_ENABLED(category)) {
     ...
 }
-</code></pre></div><h2 id=description>DESCRIPTION<a class=headerlink href=#description title="Permanent link">&para;</a></h2><p>The functions described here are mainly interesting for those who provide OpenSSL functionality, either in OpenSSL itself or in engine modules or similar.</p><p>If the tracing facility is enabled (see <a href=#configure-tracing>&quot;Configure Tracing&quot;</a> below), these functions are used to generate free text tracing output.</p><p>The tracing output is divided into types which are enabled individually by the application. The tracing types are described in detail in <a href=../OSSL_trace_set_channel/ >&quot;Trace types&quot; in OSSL_trace_set_callback(3)</a>. The fallback type <strong>OSSL_TRACE_CATEGORY_ALL</strong> should <em>not</em> be used with the functions described here.</p><p>Tracing for a specific category is enabled at run-time if a so-called <em>trace channel</em> is attached to it. A trace channel is simply a BIO object to which the application can write its trace output.</p><p>The application has two different ways of registering a trace channel, either by directly providing a BIO object using <a href=../OSSL_trace_set_channel/ >OSSL_trace_set_channel(3)</a>, or by providing a callback routine using <a href=../OSSL_trace_set_channel/ >OSSL_trace_set_callback(3)</a>. The latter is wrapped internally by a dedicated BIO object, so for the tracing code both channel types are effectively indistinguishable. We call them a <em>simple trace channel</em> and a <em>callback trace channel</em>, respectively.</p><p>To produce trace output, it is necessary to obtain a pointer to the trace channel (i.e., the BIO object) using OSSL_trace_begin(), write to it using arbitrary BIO output routines, and finally releases the channel using OSSL_trace_end(). The OSSL_trace_begin()/OSSL_trace_end() calls surrounding the trace output create a group, which acts as a critical section (guarded by a mutex) to ensure that the trace output of different threads does not get mixed up.</p><p>The tracing code normally does not call OSSL_trace_{begin,end}() directly, but rather uses a set of convenience macros, see the <a href=#macros>&quot;Macros&quot;</a> section below.</p><h3 id=functions>Functions<a class=headerlink href=#functions title="Permanent link">&para;</a></h3><p>OSSL_trace_enabled() can be used to check if tracing for the given <em>category</em> is enabled, i.e., if the tracing facility has been statically enabled (see <a href=#configure-tracing>&quot;Configure Tracing&quot;</a> below) and a trace channel has been registered using <a href=../OSSL_trace_set_channel/ >OSSL_trace_set_channel(3)</a> or <a href=../OSSL_trace_set_channel/ >OSSL_trace_set_callback(3)</a>.</p><p>OSSL_trace_begin() is used to starts a tracing section, and get the channel for the given <em>category</em> in form of a BIO. This BIO can only be used for output.</p><p>OSSL_trace_end() is used to end a tracing section.</p><p>Using OSSL_trace_begin() and OSSL_trace_end() to wrap tracing sections is <em>mandatory</em>. The result of trying to produce tracing output outside of such sections is undefined.</p><h3 id=macros>Macros<a class=headerlink href=#macros title="Permanent link">&para;</a></h3><p>There are a number of convenience macros defined, to make tracing easy and consistent.</p><p>OSSL_TRACE_BEGIN() and OSSL_TRACE_END() reserve the <strong>BIO</strong> <code>trc_out</code> and are used as follows to wrap a trace section:</p><div class=highlight><pre><span></span><code>OSSL_TRACE_BEGIN(TLS) {
+</code></pre></div><h2 id=description>DESCRIPTION<a class=headerlink href=#description title="Permanent link">&para;</a></h2><p>The functions described here are mainly interesting for those who provide OpenSSL functionality, either in OpenSSL itself or in engine modules or similar.</p><p>If the tracing facility is enabled (see <a href=#configure-tracing>&quot;Configure Tracing&quot;</a> below), these functions are used to generate free text tracing output.</p><p>The tracing output is divided into types which are enabled individually by the application. The tracing types are described in detail in <a href=../OSSL_trace_set_channel/ >&quot;Trace types&quot; in OSSL_trace_set_callback(3)</a>. The fallback type <strong>OSSL_TRACE_CATEGORY_ALL</strong> should <em>not</em> be used with the functions described here.</p><p>Tracing for a specific category is enabled at run-time if a so-called <em>trace channel</em> is attached to it. A trace channel is simply a BIO object to which the application can write its trace output.</p><p>The application has two different ways of registering a trace channel, either by directly providing a BIO object using <a href=../OSSL_trace_set_channel/ >OSSL_trace_set_channel(3)</a>, or by providing a callback routine using <a href=../OSSL_trace_set_channel/ >OSSL_trace_set_callback(3)</a>. The latter is wrapped internally by a dedicated BIO object, so for the tracing code both channel types are effectively indistinguishable. We call them a <em>simple trace channel</em> and a <em>callback trace channel</em>, respectively.</p><p>To produce trace output, it is necessary to obtain a pointer to the trace channel (i.e., the BIO object) using OSSL_trace_begin(), write to it using arbitrary BIO output routines, and finally releases the channel using OSSL_trace_end(). The OSSL_trace_begin()/OSSL_trace_end() calls surrounding the trace output create a group, which acts as a critical section (guarded by a mutex) to ensure that the trace output of different threads does not get mixed up.</p><p>The tracing code normally does not call OSSL_trace_{begin,end}() directly, but rather uses a set of convenience macros, see the <a href=#macros>&quot;Macros&quot;</a> section below.</p><h3 id=functions>Functions<a class=headerlink href=#functions title="Permanent link">&para;</a></h3><p>OSSL_trace_enabled() can be used to check if tracing for the given <em>category</em> is enabled, i.e., if the tracing facility has been statically enabled (see <a href=#configure-tracing>&quot;Configure Tracing&quot;</a> below) and a trace channel has been registered using <a href=../OSSL_trace_set_channel/ >OSSL_trace_set_channel(3)</a> or <a href=../OSSL_trace_set_channel/ >OSSL_trace_set_callback(3)</a>.</p><p>OSSL_trace_begin() is used to start a tracing section, and get the channel for the given <em>category</em> in form of a BIO. This BIO can only be used for output. The pointer returned is NULL if the category is invalid or not enabled.</p><p>OSSL_trace_end() is used to end a tracing section.</p><p>Using OSSL_trace_begin() and OSSL_trace_end() to wrap tracing sections is <em>mandatory</em>. The result of trying to produce tracing output outside of such sections is undefined.</p><h3 id=macros>Macros<a class=headerlink href=#macros title="Permanent link">&para;</a></h3><p>There are a number of convenience macros defined, to make tracing easy and consistent.</p><p>OSSL_TRACE_BEGIN() and OSSL_TRACE_END() reserve the <strong>BIO</strong> <code>trc_out</code> and are used as follows to wrap a trace section:</p><div class=highlight><pre><span></span><code>OSSL_TRACE_BEGIN(TLS) {
 
     BIO_printf(trc_out, ... );
 
@@ -79,7 +79,7 @@
 </code></pre></div><p>expands to</p><div class=highlight><pre><span></span><code>if (OSSL_trace_enabled(OSSL_TRACE_CATEGORY_TLS) {
     ...
 }
-</code></pre></div><h2 id=notes>NOTES<a class=headerlink href=#notes title="Permanent link">&para;</a></h2><p>If producing the trace output requires carrying out auxiliary calculations, this auxiliary code should be placed inside a conditional block which is executed only if the trace category is enabled.</p><p>The most natural way to do this is to place the code inside the trace section itself because it already introduces such a conditional block.</p><div class=highlight><pre><span></span><code>OSSL_TRACE_BEGIN(TLS) {
+</code></pre></div><h2 id=notes>NOTES<a class=headerlink href=#notes title="Permanent link">&para;</a></h2><p>It is not needed to guard trace output function calls like <em>OSSL_TRACE(category, ...)</em> by <em>OSSL_TRACE_ENABLED(category)</em>.</p><p>If producing the trace output requires carrying out auxiliary calculations, this auxiliary code should be placed inside a conditional block which is executed only if the trace category is enabled.</p><p>The most natural way to do this is to place the code inside the trace section itself because it already introduces such a conditional block.</p><div class=highlight><pre><span></span><code>OSSL_TRACE_BEGIN(TLS) {
     int var = do_some_auxiliary_calculation();
 
     BIO_printf(trc_out, &quot;var = %d\n&quot;, var);