individually by the application.
The tracing types are described in detail in
L<OSSL_trace_set_callback(3)/Trace types>.
-The fallback type C<OSSL_TRACE_CATEGORY_ALL> should I<not> be used
+The fallback type B<OSSL_TRACE_CATEGORY_ALL> should I<not> be used
with the functions described here.
Tracing for a specific category is enabled if a so called
=head2 Functions
OSSL_trace_enabled() can be used to check if tracing for the given
-C<category> is enabled.
+I<category> is enabled.
OSSL_trace_begin() is used to starts a tracing section, and get the
-channel for the given C<category> in form of a BIO.
+channel for the given I<category> in form of a BIO.
This BIO can only be used for output.
OSSL_trace_end() is used to end a tracing section.
There are a number of convenience macros defined, to make tracing
easy and consistent.
-C<OSSL_TRACE_BEGIN(category)> and C<OSSL_TRACE_END(category)> reserve
-the B<BIO> C<trc_out> and are used as follows to wrap a trace section:
+OSSL_TRACE_BEGIN() and OSSL_TRACE_END() reserve the B<BIO> C<trc_out> and are
+used as follows to wrap a trace section:
OSSL_TRACE_BEGIN(TLS) {
OSSL_trace_end(OSSL_TRACE_CATEGORY_TLS, trc_out);
} while (0);
-C<OSSL_TRACE_CANCEL(category)> must be used before returning from or
-jumping out of a trace section:
+OSSL_TRACE_CANCEL() must be used before returning from or jumping out of a
+trace section:
OSSL_TRACE_BEGIN(TLS) {
} while (0);
-C<OSSL_TRACE()> and C<OSSL_TRACE1()>, C<OSSL_TRACE2()>, ... C<OSSL_TRACE9()> are
+OSSL_TRACE() and OSSL_TRACE1(), OSSL_TRACE2(), ... OSSL_TRACE9() are
so-called one-shot macros:
The macro call C<OSSL_TRACE(category, text)>, produces literal text trace output.
BIO_printf(trc_out, format, arg1, ..., argN)
} OSSL_TRACE_END(category)
-Internally, all one-shot macros are implemented using a generic C<OSSL_TRACEV()>
+Internally, all one-shot macros are implemented using a generic OSSL_TRACEV()
macro, since C90 does not support variadic macros. This helper macro has a rather
weird synopsis and should not be used directly.
-The C<OSSL_TRACE_ENABLED(category)> macro can be used to conditionally execute
-some code only if a specific trace category is enabled.
+The OSSL_TRACE_ENABLED() 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
-C<OSSL_TRACE_BEGIN(category)> and C<OSSL_TRACE_END(category)>.
+OSSL_TRACE_BEGIN() and OSSL_TRACE_END().
For example, the code
if (OSSL_TRACE_ENABLED(TLS)) {
=item *
-The macro C<OPENSSL_NO_TRACE> is defined in C<openssl/opensslconf.h>.
+The macro B<OPENSSL_NO_TRACE> is defined in C<openssl/opensslconf.h>.
=item *
=head1 RETURN VALUES
-OSSL_trace_enabled() returns 1 if tracing for the given B<type> is
+OSSL_trace_enabled() returns 1 if tracing for the given I<type> is
operational and enabled, otherwise 0.
-OSSL_trace_begin() returns a C<BIO *> if the given B<type> is enabled,
-otherwise C<NULL>.
+OSSL_trace_begin() returns a B<BIO> pointer if the given I<type> is enabled,
+otherwise NULL.
=head1 HISTORY
=head2 Functions
OSSL_trace_set_channel() is used to enable the given trace C<category>
-by attaching the B<BIO> C<bio> object as (simple) trace channel.
+by attaching the B<BIO> I<bio> object as (simple) trace channel.
OSSL_trace_set_prefix() and OSSL_trace_set_suffix() can be used to add
an extra line for each channel, to be output before and after group of
OSSL_trace_set_callback() instead.
OSSL_trace_set_callback() is used to enable the given trace
-C<category> by giving it the tracer callback C<cb> with the associated
-data C<data>, which will simply be passed through to C<cb> whenever
+I<category> by giving it the tracer callback I<cb> with the associated
+data I<data>, which will simply be passed through to I<cb> whenever
it's called. The callback function is internally wrapped by a
dedicated BIO object, the so called I<callback trace channel>.
This should be used when it's desirable to do form the trace output to
exclusive, calling one of them will clear whatever was set by the
previous call.
-Calling OSSL_trace_set_channel() with C<NULL> for C<channel> or
-OSSL_trace_set_callback() with C<NULL> for C<cb> disables tracing for
-the given C<category>
+Calling OSSL_trace_set_channel() with NULL for I<channel> or
+OSSL_trace_set_callback() with NULL for I<cb> disables tracing for
+the given I<category>.
=head2 Trace callback
-The tracer callback must return a C<size_t>, which must be zero on
+The tracer callback must return a B<size_t>, which must be zero on
error and otherwise return the number of bytes that were output.
-It receives a text buffer C<buf> with C<cnt> bytes of text, as well as
-the C<category>, a control number C<cmd>, and the C<data> that was
+It receives a text buffer I<buf> with I<cnt> bytes of text, as well as
+the I<category>, a control number I<cmd>, and the I<data> that was
passed to OSSL_trace_set_callback().
The possible control numbers are:
=over 4
-=item C<OSSL_TRACE_CTRL_BEGIN>
+=item B<OSSL_TRACE_CTRL_BEGIN>
The callback is called from OSSL_trace_begin(), which gives the
callback the possibility to output a dynamic starting line, or set a
prefix that should be output at the beginning of each line, or
something other.
-=item C<OSSL_TRACE_CTRL_WRITE>
+=item B<OSSL_TRACE_CTRL_WRITE>
This callback is called whenever data is written to the BIO by some
regular BIO output routine.
-An arbitrary number of C<OSSL_TRACE_CTRL_WRITE> callbacks can occur
-inside a group marked by a pair of C<OSSL_TRACE_CTRL_BEGIN> and
-C<OSSL_TRACE_CTRL_END> calls, but never outside such a group.
+An arbitrary number of B<OSSL_TRACE_CTRL_WRITE> callbacks can occur
+inside a group marked by a pair of B<OSSL_TRACE_CTRL_BEGIN> and
+B<OSSL_TRACE_CTRL_END> calls, but never outside such a group.
-=item C<OSSL_TRACE_CTRL_END>
+=item B<OSSL_TRACE_CTRL_END>
The callback is called from OSSL_trace_end(), which gives the callback
the possibility to output a dynamic ending line, or reset the line
-prefix that was set with OSSL_TRACE_CTRL_BEGIN, or something other.
+prefix that was set with B<OSSL_TRACE_CTRL_BEGIN>, or something other.
=back
=over 4
-=item C<OSSL_TRACE_CATEGORY_TRACE>
+=item B<OSSL_TRACE_CATEGORY_TRACE>
Traces the OpenSSL trace API itself.
More precisely, this will generate trace output any time a new
trace hook is set.
-=item C<OSSL_TRACE_CATEGORY_INIT>
+=item B<OSSL_TRACE_CATEGORY_INIT>
Traces OpenSSL library initialization and cleanup.
A suggestion is to make such cleanup part of a function that's
registered very early with L<atexit(3)>.
-=item C<OSSL_TRACE_CATEGORY_TLS>
+=item B<OSSL_TRACE_CATEGORY_TLS>
Traces the TLS/SSL protocol.
-=item C<OSSL_TRACE_CATEGORY_TLS_CIPHER>
+=item B<OSSL_TRACE_CATEGORY_TLS_CIPHER>
Traces the ciphers used by the TLS/SSL protocol.
-=item C<OSSL_TRACE_CATEGORY_ENGINE_TABLE>
+=item B<OSSL_TRACE_CATEGORY_ENGINE_TABLE>
Traces the ENGINE algorithm table selection.
RSA, DSA (etc) code to select registered ENGINEs, cache defaults and
functional references (etc), will generate trace summaries.
-=item C<OSSL_TRACE_CATEGORY_ENGINE_REF_COUNT>
+=item B<OSSL_TRACE_CATEGORY_ENGINE_REF_COUNT>
-Tracds the ENGINE reference counting.
+Traces the ENGINE reference counting.
More precisely, both reference counts in the ENGINE structure will be
monitored with a line of trace output generated for each change.
-=item C<OSSL_TRACE_CATEGORY_PKCS5V2>
+=item B<OSSL_TRACE_CATEGORY_PKCS5V2>
Traces PKCS#5 v2 key generation.
-=item C<OSSL_TRACE_CATEGORY_PKCS12_KEYGEN>
+=item B<OSSL_TRACE_CATEGORY_PKCS12_KEYGEN>
Traces PKCS#12 key generation.
-=item C<OSSL_TRACE_CATEGORY_PKCS12_DECRYPT>
+=item B<OSSL_TRACE_CATEGORY_PKCS12_DECRYPT>
Traces PKCS#12 decryption.
-=item C<OSSL_TRACE_CATEGORY_X509V3_POLICY>
+=item B<OSSL_TRACE_CATEGORY_X509V3_POLICY>
Traces X509v3 policy processing.
More precisely, this generates the complete policy tree at various
point during evaluation.
-=item C<OSSL_TRACE_CATEGORY_BN_CTX>
+=item B<OSSL_TRACE_CATEGORY_BN_CTX>
Traces BIGNUM context operations.
-=item C<OSSL_TRACE_CATEGORY_CONF>
+=item B<OSSL_TRACE_CATEGORY_CONF>
Traces details about the provider and engine configuration.
=back
-There is also C<OSSL_TRACE_CATEGORY_ALL>, which works as a fallback
+There is also B<OSSL_TRACE_CATEGORY_ALL>, which works as a fallback
and can be used to get I<all> trace output.
Note, however, that in this case all trace output will effectively be
necessary to configure and build OpenSSL with the 'enable-trace' option.
When the library is built with tracing disabled, the macro
-C<OPENSSL_NO_TRACE> is defined in C<openssl/opensslconf.h> and all
+B<OPENSSL_NO_TRACE> is defined in C<openssl/opensslconf.h> and all
functions described here are inoperational, i.e. will do nothing.
=head1 HISTORY