From: Dr. David von Oheimb Date: Tue, 24 May 2022 18:33:32 +0000 (+0200) Subject: OSSL_trace_enabled.pod and OSSL_trace_set_channel.pod: improve doc X-Git-Tag: openssl-3.2.0-alpha1~2597 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=3b7398843c1cfd170494a03a4be54042fb821172;p=thirdparty%2Fopenssl.git OSSL_trace_enabled.pod and OSSL_trace_set_channel.pod: improve doc Reviewed-by: Tomas Mraz Reviewed-by: Dmitry Belyavskiy Reviewed-by: David von Oheimb (Merged from https://github.com/openssl/openssl/pull/18386) --- diff --git a/doc/man3/OSSL_trace_enabled.pod b/doc/man3/OSSL_trace_enabled.pod index f9c9dffd8c6..94af9f44c2c 100644 --- a/doc/man3/OSSL_trace_enabled.pod +++ b/doc/man3/OSSL_trace_enabled.pod @@ -49,8 +49,8 @@ The functions described here are mainly interesting for those who provide OpenSSL functionality, either in OpenSSL itself or in engine modules or similar. -If tracing is enabled (see L below), these functions are used to -generate free text tracing output. +If the tracing facility is enabled (see L 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. @@ -59,13 +59,13 @@ L. The fallback type B should I 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 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, +or by providing a callback routine using L. 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 and a I, @@ -86,7 +86,9 @@ but rather uses a set of convenience macros, see the L section below. =head2 Functions OSSL_trace_enabled() can be used to check if tracing for the given -I is enabled. +I is enabled, i.e., if the tracing facility has been statically +enabled (see L below) and a trace channel has been +registered using L or L. OSSL_trace_begin() is used to starts a tracing section, and get the channel for the given I in form of a BIO. @@ -109,7 +111,7 @@ used as follows to wrap a trace section: OSSL_TRACE_BEGIN(TLS) { - BIO_fprintf(trc_out, ... ); + BIO_printf(trc_out, ... ); } OSSL_TRACE_END(TLS); @@ -119,7 +121,7 @@ This will normally expand to: 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); @@ -133,7 +135,7 @@ trace section: OSSL_TRACE_CANCEL(TLS); goto err; } - BIO_fprintf(trc_out, ... ); + BIO_printf(trc_out, ... ); } OSSL_TRACE_END(TLS); @@ -146,7 +148,7 @@ This will normally expand to: 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); @@ -249,7 +251,7 @@ For example, take this example from L section above: OSSL_TRACE_CANCEL(TLS); goto err; } - BIO_fprintf(trc_out, ... ); + BIO_printf(trc_out, ... ); } OSSL_TRACE_END(TLS); @@ -262,7 +264,7 @@ When the tracing API isn't operational, that will expand to: ((void)0); goto err; } - BIO_fprintf(trc_out, ... ); + BIO_printf(trc_out, ... ); } } while (0); @@ -276,6 +278,10 @@ operational and enabled, otherwise 0. OSSL_trace_begin() returns a B pointer if the given I is enabled, otherwise NULL. +=head1 SEE ALSO + +L, L + =head1 HISTORY The OpenSSL Tracing API was added in OpenSSL 3.0. diff --git a/doc/man3/OSSL_trace_set_channel.pod b/doc/man3/OSSL_trace_set_channel.pod index 481d7162cf0..22741b2e736 100644 --- a/doc/man3/OSSL_trace_set_channel.pod +++ b/doc/man3/OSSL_trace_set_channel.pod @@ -21,13 +21,13 @@ OSSL_trace_set_callback, OSSL_trace_cb - Enabling trace output =head1 DESCRIPTION -If available (see L below), the application can request +If available (see L 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 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 @@ -38,6 +38,11 @@ For the tracing code, both trace channel types are indistinguishable. These are called a I and a I, respectively. +L can be used to check whether tracing is currently +enabled for the given category. +Functions like L and macros like L +can be used for producing free-text trace output. + =head2 Functions OSSL_trace_set_channel() is used to enable the given trace C @@ -56,7 +61,7 @@ OSSL_trace_set_callback() is used to enable the given trace I by giving it the tracer callback I with the associated data I, which will simply be passed through to I whenever it's called. The callback function is internally wrapped by a -dedicated BIO object, the so called I. +dedicated BIO object, the so-called I. 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. @@ -292,6 +297,11 @@ When the library is built with tracing disabled, the macro B is defined in F<< >> and all functions described here are inoperational, i.e. will do nothing. +=head1 SEE ALSO + +L, L, L, +L + =head1 HISTORY OSSL_trace_set_channel(), OSSL_trace_set_prefix(),