OSSL_trace_enabled.pod and OSSL_trace_set_channel.pod: improve doc

Reviewed-by: Tomas Mraz <tomas@openssl.org>
Reviewed-by: Dmitry Belyavskiy <beldmit@gmail.com>
Reviewed-by: David von Oheimb <david.von.oheimb@siemens.com>
(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 f9c9dffd8c6a8ae1afa650a608ddc6b32ed56886..94af9f44c2c6f9f61934c29c4b6bb92bc326ec13 100644 (file)
--- 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</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.
@@ -59,13 +59,13 @@ L<OSSL_trace_set_callback(3)/Trace types>.
 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>,
@@ -86,7 +86,9 @@ but rather uses a set of convenience macros, see the L</Macros> section below.
 =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.
@@ -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</Macros> 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<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.

diff --git a/doc/man3/OSSL_trace_set_channel.pod b/doc/man3/OSSL_trace_set_channel.pod
index 481d7162cf0cc09ee9984e748dd82a000a908802..22741b2e736b89690efeda64ccd578abf7e866dc 100644 (file)
--- 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</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
@@ -38,6 +38,11 @@ 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.
 
+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>
@@ -56,7 +61,7 @@ OSSL_trace_set_callback() is used to enable the given trace
 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.
@@ -292,6 +297,11 @@ When the library is built with tracing disabled, the macro
 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(),