OpenSSL functionality, either in OpenSSL itself or in engine modules
or similar.
-If tracing is enabled (see L</NOTES> below), these functions are used to
-generate free text tracing output.
+If the tracing facility is enabled (see L</Configure Tracing> 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 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
+Tracing for a specific category is enabled at run-time if a so-called
I<trace channel> is attached to it. A trace channel is simply a
BIO 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 BIO object using OSSL_trace_set_channel(),
-or by providing a callback routine using OSSL_trace_set_callback().
+either by directly providing a BIO object using L<OSSL_trace_set_channel(3)>,
+or by providing a callback routine using L<OSSL_trace_set_callback(3)>.
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 I<simple trace channel> and a I<callback trace channel>,
=head2 Functions
OSSL_trace_enabled() can be used to check if tracing for the given
-I<category> is enabled.
+I<category> is enabled, i.e., if the tracing facility has been statically
+enabled (see L</Configure Tracing> below) and a trace channel has been
+registered using L<OSSL_trace_set_channel(3)> or L<OSSL_trace_set_callback(3)>.
OSSL_trace_begin() is used to starts a tracing section, and get the
channel for the given I<category> in form of a BIO.
OSSL_TRACE_BEGIN(TLS) {
- BIO_fprintf(trc_out, ... );
+ BIO_printf(trc_out, ... );
} OSSL_TRACE_END(TLS);
BIO *trc_out = OSSL_trace_begin(OSSL_TRACE_CATEGORY_TLS);
if (trc_out != NULL) {
...
- BIO_fprintf(trc_out, ...);
+ BIO_printf(trc_out, ...);
}
OSSL_trace_end(OSSL_TRACE_CATEGORY_TLS, trc_out);
} while (0);
OSSL_TRACE_CANCEL(TLS);
goto err;
}
- BIO_fprintf(trc_out, ... );
+ BIO_printf(trc_out, ... );
} OSSL_TRACE_END(TLS);
OSSL_trace_end(OSSL_TRACE_CATEGORY_TLS, trc_out);
goto err;
}
- BIO_fprintf(trc_out, ... );
+ BIO_printf(trc_out, ... );
}
OSSL_trace_end(OSSL_TRACE_CATEGORY_TLS, trc_out);
} while (0);
OSSL_TRACE_CANCEL(TLS);
goto err;
}
- BIO_fprintf(trc_out, ... );
+ BIO_printf(trc_out, ... );
} OSSL_TRACE_END(TLS);
((void)0);
goto err;
}
- BIO_fprintf(trc_out, ... );
+ BIO_printf(trc_out, ... );
}
} while (0);
OSSL_trace_begin() returns a B<BIO> pointer if the given I<type> is enabled,
otherwise NULL.
+=head1 SEE ALSO
+
+L<OSSL_trace_set_channel(3)>, L<OSSL_trace_set_callback(3)>
+
=head1 HISTORY
The OpenSSL Tracing API was added in OpenSSL 3.0.
=head1 DESCRIPTION
-If available (see L</NOTES> below), the application can request
+If available (see L</Configure Tracing> below), the application can request
internal trace output.
This output comes in form of free text for humans to read.
The trace output is divided into categories which can be
enabled individually.
-Every category can be enabled individually by attaching a so called
+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
These are called a I<simple trace channel> and a I<callback trace channel>,
respectively.
+L<OSSL_TRACE_ENABLED(3)> can be used to check whether tracing is currently
+enabled for the given category.
+Functions like L<OSSL_TRACE1(3)> and macros like L<OSSL_TRACE_BEGIN(3)>
+can be used for producing free-text trace output.
+
=head2 Functions
OSSL_trace_set_channel() is used to enable the given trace C<category>
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>.
+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.
B<OPENSSL_NO_TRACE> is defined in F<< <openssl/opensslconf.h> >> and all
functions described here are inoperational, i.e. will do nothing.
+=head1 SEE ALSO
+
+L<OSSL_TRACE_ENABLED(3)>, L<OSSL_TRACE_BEGIN(3)>, L<OSSL_TRACE1(3)>,
+L<atexit(3)>
+
=head1 HISTORY
OSSL_trace_set_channel(), OSSL_trace_set_prefix(),