The trace output is divided into categories which can be
enabled individually.
-They are enabled by giving them a channel in form of a BIO, or a
-tracer callback, which is responsible for performing the actual
-output.
+Every category can be enabled individually by attaching a so called
+I<trace channel> to it, which in the simplest case is just a BIO object
+to which the application can write the tracing output for this category.
+Alternatively, the application can provide a tracer callback in order to
+get more finegrained trace information. This callback will be wrapped
+internally by a dedicated BIO object.
+
+For the tracing code, both trace channel types are indistinguishable.
+These are called a I<simple trace channel> and a I<callback trace channel>,
+respectively.
=head2 Functions
OSSL_trace_set_channel() is used to enable the given trace C<category>
-by giving it the B<BIO> C<bio>.
+by attaching the B<BIO> C<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() 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
-it's called.
+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
something suitable for application needs where a prefix and suffix
line aren't enough.
prefix that should be output at the beginning of each line, or
something other.
-=item C<OSSL_TRACE_CTRL_DURING>
+=item C<OSSL_TRACE_CTRL_WRITE>
-The callback is called from any regular BIO output routine.
+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.
=item C<OSSL_TRACE_CTRL_END>
Traces BIGNUM context operations.
+=item C<OSSL_TRACE_CATEGORY_PROVIDER_CONF>
+
+Traces the OSSL_PROVIDER configuration.
+
=back
-There is also C<OSSL_TRACE_CATEGORY_ANY>, which works as a fallback
+There is also C<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
+associated with the 'ALL' category, which is undesirable if the
+application intends to include the category name in the trace output.
+In this case it is better to register separate channels for each
+trace category instead.
+
=head1 RETURN VALUES
OSSL_trace_set_channel(), OSSL_trace_set_prefix(),
=head1 EXAMPLES
-In all examples below, we assume that the trace producing code is
-this:
+In all examples below, the trace producing code is assumed to be
+the following:
int foo = 42;
const char bar[] = { 0, 1, 2, 3, 4, 5, 6, 7,
=head1 NOTES
-=head2 Tracing disabled
+=head2 Configure Tracing
-The OpenSSL library may be built with tracing disabled, which makes
-everything documented here inoperational.
+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.
When the library is built with tracing disabled, the macro
C<OPENSSL_NO_TRACE> is defined in C<openssl/opensslconf.h> and all
projects / openssl.git / blobdiff