309 lines
11 KiB
HTML
Executable File
309 lines
11 KiB
HTML
Executable File
<?xml version="1.0" ?>
|
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
|
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
|
<head>
|
|
<title>OSSL_trace_enabled</title>
|
|
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
|
|
<link rev="made" href="mailto:root@localhost" />
|
|
</head>
|
|
|
|
<body style="background-color: white">
|
|
|
|
|
|
<!-- INDEX BEGIN -->
|
|
<div name="index">
|
|
<p><a name="__index__"></a></p>
|
|
|
|
<ul>
|
|
|
|
<li><a href="#name">NAME</a></li>
|
|
<li><a href="#synopsis">SYNOPSIS</a></li>
|
|
<li><a href="#description">DESCRIPTION</a></li>
|
|
<ul>
|
|
|
|
<li><a href="#functions">Functions</a></li>
|
|
<li><a href="#macros">Macros</a></li>
|
|
</ul>
|
|
|
|
<li><a href="#notes">NOTES</a></li>
|
|
<ul>
|
|
|
|
<li><a href="#configure_tracing">Configure Tracing</a></li>
|
|
</ul>
|
|
|
|
<li><a href="#return_values">RETURN VALUES</a></li>
|
|
<li><a href="#history">HISTORY</a></li>
|
|
<li><a href="#copyright">COPYRIGHT</a></li>
|
|
</ul>
|
|
|
|
<hr name="index" />
|
|
</div>
|
|
<!-- INDEX END -->
|
|
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="name">NAME</a></h1>
|
|
<p>OSSL_trace_enabled, OSSL_trace_begin, OSSL_trace_end,
|
|
OSSL_TRACE_BEGIN, OSSL_TRACE_END, OSSL_TRACE_CANCEL,
|
|
OSSL_TRACE, OSSL_TRACE1, OSSL_TRACE2, OSSL_TRACE3, OSSL_TRACE4,
|
|
OSSL_TRACE5, OSSL_TRACE6, OSSL_TRACE7, OSSL_TRACE8, OSSL_TRACE9,
|
|
OSSL_TRACEV,
|
|
OSSL_TRACE_ENABLED
|
|
- OpenSSL Tracing API</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="synopsis">SYNOPSIS</a></h1>
|
|
<pre>
|
|
#include <openssl/trace.h></pre>
|
|
<pre>
|
|
int OSSL_trace_enabled(int category);</pre>
|
|
<pre>
|
|
BIO *OSSL_trace_begin(int category);
|
|
void OSSL_trace_end(int category, BIO *channel);</pre>
|
|
<pre>
|
|
/* trace group macros */
|
|
OSSL_TRACE_BEGIN(category) {
|
|
...
|
|
if (some_error) {
|
|
/* Leave trace group prematurely in case of an error */
|
|
OSSL_TRACE_CANCEL(category);
|
|
goto err;
|
|
}
|
|
...
|
|
} OSSL_TRACE_END(category);</pre>
|
|
<pre>
|
|
/* one-shot trace macros */
|
|
OSSL_TRACE1(category, format, arg1)
|
|
OSSL_TRACE2(category, format, arg1, arg2)
|
|
...
|
|
OSSL_TRACE9(category, format, arg1, ..., arg9)</pre>
|
|
<pre>
|
|
/* check whether a trace category is enabled */
|
|
if (OSSL_TRACE_ENABLED(category)) {
|
|
...
|
|
}</pre>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="description">DESCRIPTION</a></h1>
|
|
<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 tracing is enabled (see <a href="#notes">NOTES</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
|
|
<em>OSSL_trace_set_callback(3)/Trace types</em>.
|
|
The fallback type <code>OSSL_TRACE_CATEGORY_ALL</code> should <em>not</em> be used
|
|
with the functions described here.</p>
|
|
<p>Tracing for a specific category is enabled 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 <code>OSSL_trace_set_channel()</code>,
|
|
or by providing a callback routine using <code>OSSL_trace_set_callback()</code>.
|
|
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 <code>OSSL_trace_begin()</code>, write
|
|
to it using arbitrary BIO output routines, and finally releases the
|
|
channel using <code>OSSL_trace_end()</code>. 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">Macros</a> section below.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="functions">Functions</a></h2>
|
|
<p><code>OSSL_trace_enabled()</code> can be used to check if tracing for the given
|
|
<code>category</code> is enabled.</p>
|
|
<p><code>OSSL_trace_begin()</code> is used to starts a tracing section, and get the
|
|
channel for the given <code>category</code> in form of a BIO.
|
|
This BIO can only be used for output.</p>
|
|
<p><code>OSSL_trace_end()</code> is used to end a tracing section.</p>
|
|
<p>Using <code>OSSL_trace_begin()</code> and <code>OSSL_trace_end()</code> to wrap tracing sections
|
|
is <em>mandatory</em>.
|
|
The result of trying to produce tracing output outside of such
|
|
sections is undefined.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="macros">Macros</a></h2>
|
|
<p>There are a number of convenience macros defined, to make tracing
|
|
easy and consistent.</p>
|
|
<p><code>OSSL_TRACE_BEGIN(category)</code> and <code>OSSL_TRACE_END(category)</code> reserve
|
|
the <strong>BIO</strong> <code>trc_out</code> and are used as follows to wrap a trace section:</p>
|
|
<pre>
|
|
OSSL_TRACE_BEGIN(TLS) {</pre>
|
|
<pre>
|
|
BIO_fprintf(trc_out, ... );</pre>
|
|
<pre>
|
|
} OSSL_TRACE_END(TLS);</pre>
|
|
<p>This will normally expand to:</p>
|
|
<pre>
|
|
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);</pre>
|
|
<p><code>OSSL_TRACE_CANCEL(category)</code> must be used before returning from or
|
|
jumping out of a trace section:</p>
|
|
<pre>
|
|
OSSL_TRACE_BEGIN(TLS) {</pre>
|
|
<pre>
|
|
if (some_error) {
|
|
OSSL_TRACE_CANCEL(TLS);
|
|
goto err;
|
|
}
|
|
BIO_fprintf(trc_out, ... );</pre>
|
|
<pre>
|
|
} OSSL_TRACE_END(TLS);</pre>
|
|
<p>This will normally expand to:</p>
|
|
<pre>
|
|
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);</pre>
|
|
<p><code>OSSL_TRACE()</code> and <code>OSSL_TRACE1()</code>, <code>OSSL_TRACE2()</code>, ... <code>OSSL_TRACE9()</code> are
|
|
so-called one-shot macros:</p>
|
|
<p>The macro call <code>OSSL_TRACE(category, text)</code>, produces literal text trace output.</p>
|
|
<p>The macro call <code>OSSL_TRACEn(category, format, arg1, ..., argn)</code> produces
|
|
printf-style trace output with n format field arguments (n=1,...,9).
|
|
It expands to:</p>
|
|
<pre>
|
|
OSSL_TRACE_BEGIN(category) {
|
|
BIO_printf(trc_out, format, arg1, ..., argN)
|
|
} OSSL_TRACE_END(category)</pre>
|
|
<p>Internally, all one-shot macros are implemented using a generic <code>OSSL_TRACEV()</code>
|
|
macro, since C90 does not support variadic macros. This helper macro has a rather
|
|
weird synopsis and should not be used directly.</p>
|
|
<p>The <code>OSSL_TRACE_ENABLED(category)</code> 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
|
|
<code>OSSL_TRACE_BEGIN(category)</code> and <code>OSSL_TRACE_END(category)</code>.
|
|
For example, the code</p>
|
|
<pre>
|
|
if (OSSL_TRACE_ENABLED(TLS)) {
|
|
...
|
|
}</pre>
|
|
<p>expands to</p>
|
|
<pre>
|
|
if (OSSL_trace_enabled(OSSL_TRACE_CATEGORY_TLS) {
|
|
...
|
|
}</pre>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="notes">NOTES</a></h1>
|
|
<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>
|
|
<pre>
|
|
OSSL_TRACE_BEGIN(TLS) {
|
|
int var = do_some_auxiliary_calculation();</pre>
|
|
<pre>
|
|
BIO_printf(trc_out, "var = %d\n", var);</pre>
|
|
<pre>
|
|
} OSSL_TRACE_END(TLS);</pre>
|
|
<p>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.</p>
|
|
<pre>
|
|
if (OSSL_TRACE_ENABLED(TLS)) {
|
|
int var = do_some_auxiliary_calculation();</pre>
|
|
<pre>
|
|
OSSL_TRACE1("var = %d\n", var);
|
|
}</pre>
|
|
<p>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.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="configure_tracing">Configure Tracing</a></h2>
|
|
<p>By default, the OpenSSL library is built with tracing disabled. To
|
|
use the tracing functionality documented here, it is therefore
|
|
necessary to configure and build OpenSSL with the 'enable-trace' option.</p>
|
|
<p>When the library is built with tracing disabled:</p>
|
|
<ul>
|
|
<li>
|
|
<p>The macro <code>OPENSSL_NO_TRACE</code> is defined in <code>openssl/opensslconf.h</code>.</p>
|
|
</li>
|
|
<li>
|
|
<p>all functions are still present, bu <code>OSSL_trace_enabled()</code> will always
|
|
report the categories as disabled, and all other functions will do
|
|
nothing.</p>
|
|
</li>
|
|
<li>
|
|
<p>the convenience macros are defined to produce dead code.
|
|
For example, take this example from <a href="#macros">Macros</a> section above:</p>
|
|
<pre>
|
|
OSSL_TRACE_BEGIN(TLS) {</pre>
|
|
<pre>
|
|
if (condition) {
|
|
OSSL_TRACE_CANCEL(TLS);
|
|
goto err;
|
|
}
|
|
BIO_fprintf(trc_out, ... );</pre>
|
|
<pre>
|
|
} OSSL_TRACE_END(TLS);</pre>
|
|
<p>When the tracing API isn't operational, that will expand to:</p>
|
|
<pre>
|
|
do {
|
|
BIO *trc_out = NULL;
|
|
if (0) {
|
|
if (condition) {
|
|
((void)0);
|
|
goto err;
|
|
}
|
|
BIO_fprintf(trc_out, ... );
|
|
}
|
|
} while (0);</pre>
|
|
</li>
|
|
</ul>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="return_values">RETURN VALUES</a></h1>
|
|
<p><code>OSSL_trace_enabled()</code> returns 1 if tracing for the given <strong>type</strong> is
|
|
operational and enabled, otherwise 0.</p>
|
|
<p><code>OSSL_trace_begin()</code> returns a <code>BIO *</code> if the given <strong>type</strong> is enabled,
|
|
otherwise <code>NULL</code>.</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="history">HISTORY</a></h1>
|
|
<p>The OpenSSL Tracing API was added ino OpenSSL 3.0.</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="copyright">COPYRIGHT</a></h1>
|
|
<p>Copyright 2019 The OpenSSL Project Authors. All Rights Reserved.</p>
|
|
<p>Licensed under the Apache License 2.0 (the "License"). You may not use
|
|
this file except in compliance with the License. You can obtain a copy
|
|
in the file LICENSE in the source distribution or at
|
|
<a href="https://www.openssl.org/source/license.html">https://www.openssl.org/source/license.html</a>.</p>
|
|
|
|
</body>
|
|
|
|
</html>
|