Standard preamble:
========================================================================
..
.... Set up some character translations and predefined strings. \*(-- will
give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
double quote, and \*(R" will give a right double quote. \*(C+ will
give a nicer C++. Capital omega is used to do unbreakable dashes and
therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
nothing in troff, for use with C<>.
.tr \(*W- . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\}
Escape single quotes in literal strings from groff's Unicode transform.
If the F register is >0, we'll generate index entries on stderr for
titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
entries marked with X<> in POD. Of course, you'll have to process the
output yourself in some meaningful fashion.
Avoid warning from groff about undefined register 'F'.
.. .nr rF 0 . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] .\} . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents . \" corrections for vroff . \" for low resolution devices (crt and lpr) \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} ========================================================================
Title "OSSL_TRACE_ENABLED 3ossl"
way too many mistakes in technical documents.
If tracing is enabled (see \*(L"\s-1NOTES\*(R"\s0 below), these functions are used to generate free text tracing output.
The tracing output is divided into types which are enabled individually by the application. The tracing types are described in detail in \*(L"Trace types\*(R" in OSSL_trace_set_callback\|(3). The fallback type \s-1OSSL_TRACE_CATEGORY_ALL\s0 should not be used with the functions described here.
Tracing for a specific category is enabled if a so called \fItrace channel is attached to it. A trace channel is simply a \s-1BIO\s0 object to which the application can write its trace output.
The application has two different ways of registering a trace channel, either by directly providing a \s-1BIO\s0 object using OSSL_trace_set_channel(), or by providing a callback routine using OSSL_trace_set_callback(). The latter is wrapped internally by a dedicated \s-1BIO\s0 object, so for the tracing code both channel types are effectively indistinguishable. We call them a simple trace channel and a callback trace channel, respectively.
To produce trace output, it is necessary to obtain a pointer to the trace channel (i.e., the \s-1BIO\s0 object) using OSSL_trace_begin(), write to it using arbitrary \s-1BIO\s0 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.
The tracing code normally does not call OSSL_trace_{begin,end}() directly, but rather uses a set of convenience macros, see the \*(L"Macros\*(R" section below.
\fBOSSL_trace_begin() is used to starts a tracing section, and get the channel for the given category in form of a \s-1BIO.\s0 This \s-1BIO\s0 can only be used for output.
\fBOSSL_trace_end() is used to end a tracing section.
Using OSSL_trace_begin() and OSSL_trace_end() to wrap tracing sections is mandatory. The result of trying to produce tracing output outside of such sections is undefined.
\s-1OSSL_TRACE_BEGIN\s0() and \s-1OSSL_TRACE_END\s0() reserve the \s-1BIO\s0 \*(C`trc_out\*(C' and are used as follows to wrap a trace section:
.Vb 1 OSSL_TRACE_BEGIN(TLS) { \& BIO_fprintf(trc_out, ... ); \& } OSSL_TRACE_END(TLS); .Ve
This will normally expand to:
.Vb 8 do { BIO *trc_out = OSSL_trace_begin(OSSL_TRACE_CATEGORY_TLS); if (trc_out != NULL) { ... BIO_fprintf(trc_out, ...); } OSSL_trace_end(OSSL_TRACE_CATEGORY_TLS, trc_out); } while (0); .Ve
\s-1OSSL_TRACE_CANCEL\s0() must be used before returning from or jumping out of a trace section:
.Vb 1 OSSL_TRACE_BEGIN(TLS) { \& if (some_error) { OSSL_TRACE_CANCEL(TLS); goto err; } BIO_fprintf(trc_out, ... ); \& } OSSL_TRACE_END(TLS); .Ve
This will normally expand to:
.Vb 11 do { BIO *trc_out = OSSL_trace_begin(OSSL_TRACE_CATEGORY_TLS); if (trc_out != NULL) { if (some_error) { OSSL_trace_end(OSSL_TRACE_CATEGORY_TLS, trc_out); goto err; } BIO_fprintf(trc_out, ... ); } OSSL_trace_end(OSSL_TRACE_CATEGORY_TLS, trc_out); } while (0); .Ve
\s-1OSSL_TRACE\s0() and \s-1OSSL_TRACE1\s0(), \s-1OSSL_TRACE2\s0(), ... \s-1OSSL_TRACE9\s0() are so-called one-shot macros:
The macro call \*(C`OSSL_TRACE(category, text)\*(C', produces literal text trace output.
The macro call \*(C`OSSL_TRACEn(category, format, arg1, ..., argn)\*(C' produces printf-style trace output with n format field arguments (n=1,...,9). It expands to:
.Vb 3 OSSL_TRACE_BEGIN(category) { BIO_printf(trc_out, format, arg1, ..., argN) } OSSL_TRACE_END(category) .Ve
Internally, all one-shot macros are implemented using a generic \s-1OSSL_TRACEV\s0() macro, since C90 does not support variadic macros. This helper macro has a rather weird synopsis and should not be used directly.
The \s-1OSSL_TRACE_ENABLED\s0() macro can be used to conditionally execute some code only if a specific trace category is enabled. In some situations this is simpler than entering a trace section using \s-1OSSL_TRACE_BEGIN\s0() and \s-1OSSL_TRACE_END\s0(). For example, the code
.Vb 3 if (OSSL_TRACE_ENABLED(TLS)) { ... } .Ve
expands to
.Vb 3 if (OSSL_trace_enabled(OSSL_TRACE_CATEGORY_TLS) { ... } .Ve
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.
.Vb 2 OSSL_TRACE_BEGIN(TLS) { int var = do_some_auxiliary_calculation(); \& BIO_printf(trc_out, "var = %d\en", var); \& } OSSL_TRACE_END(TLS); .Ve
In some cases it is more advantageous to use a simple conditional group instead of a trace section. This is the case if calculations and tracing happen in different locations of the code, or if the calculations are so time consuming that placing them inside a (critical) trace section would create too much contention.
.Vb 2 if (OSSL_TRACE_ENABLED(TLS)) { int var = do_some_auxiliary_calculation(); \& OSSL_TRACE1("var = %d\en", var); } .Ve
Note however that premature optimization of tracing code is in general futile and it's better to keep the tracing code as simple as possible. Because most often the limiting factor for the application's speed is the time it takes to print the trace output, not to calculate it.
When the library is built with tracing disabled:
\fBOSSL_trace_begin() returns a \s-1BIO\s0 pointer if the given type is enabled, otherwise \s-1NULL.\s0
Licensed under the Apache License 2.0 (the \*(L"License\*(R"). You may not use this file except in compliance with the License. You can obtain a copy in the file \s-1LICENSE\s0 in the source distribution or at <https://www.openssl.org/source/license.html>.