trace: add PROVIDER_CONF trace category

[openssl.git] / doc / man3 / OSSL_trace_enabled.pod

diff --git a/doc/man3/OSSL_trace_enabled.pod b/doc/man3/OSSL_trace_enabled.pod
index ecb88ab0ab695848f3b38a6906d51943b716770b..e26dee5370121bd14092ab2e924462abf6ec13a1 100644 (file)
--- a/doc/man3/OSSL_trace_enabled.pod
+++ b/doc/man3/OSSL_trace_enabled.pod
@@ -2,7 +2,8 @@
 
 =head1 NAME
 
-OSSL_trace_enabled, OSSL_trace_begin, OSSL_trace_end
+OSSL_trace_enabled, OSSL_trace_begin, OSSL_trace_end,
+OSSL_TRACE_BEGIN, OSSL_TRACE_END, OSSL_TRACE1, OSSL_TRACE2, OSSL_TRACE9
 - OpenSSL Tracing API
 
 =head1 SYNOPSIS
@@ -14,22 +15,58 @@ OSSL_trace_enabled, OSSL_trace_begin, OSSL_trace_end
  BIO *OSSL_trace_begin(int category);
  void OSSL_trace_end(int category, BIO *channel);
 
+ /* trace group macros */
+ OSSL_TRACE_BEGIN(category) {
+    ...
+ } OSSL_TRACE_END(category);
+
+ /* one-shot trace macros */
+ OSSL_TRACE1(category, format, arg1)
+ OSSL_TRACE2(category, format, arg1, arg2)
+ ...
+ OSSL_TRACE9(category, format, arg1, ..., arg9)
+
+
 =head1 DESCRIPTION
 
 The functions described here are mainly interesting for those who provide
 OpenSSL functionality, either in OpenSSL itself or in engine modules
 or similar.
 
-If operational (see L</NOTES> below), these functions are used to
+If tracing is enabled (see L</NOTES> 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 tracing types are described in detail in
 L<OSSL_trace_set_callback(3)/Trace types>.
-The fallback type C<OSSL_TRACE_CATEGORY_ANY> should I<not> be used
+The fallback type C<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
+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().
+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>,
+respectively.
+
+To produce trace output, it is necessary to obtain a pointer to the
+trace channel (i.e., the BIO object) using OSSL_trace_begin(), write
+to it using arbitrary BIO output routines, and finally releases the
+channel using OSSL_trace_end(). The OSSL_trace_begin()/OSSL_trace_end()
+calls surrounding the trace output create a group, which acts as a
+critical section (guarded by a mutex) to ensure that the trace output
+of different threads does not get mixed up.
+
+The tracing code normally does not call OSSL_trace_{begin,end}() directly,
+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
@@ -46,7 +83,7 @@ is I<mandatory>.
 The result of trying to produce tracing output outside of such
 sections is undefined.
 
-=head2 Convenience Macros
+=head2 Macros
 
 There are a number of convenience macros defined, to make tracing
 easy and consistent.
@@ -60,7 +97,7 @@ the B<BIO> C<trc_out> and are used as follows to wrap a trace section:
 
  } OSSL_TRACE_END(TLS);
 
-This will normally expands to:
+This will normally expand to:
 
  do {
      BIO *trc_out = OSSL_trace_begin(OSSL_TRACE_CATEGORY_TLS);
@@ -98,6 +135,16 @@ This will normally expand to:
      OSSL_trace_end(OSSL_TRACE_CATEGORY_TLS, trc_out);
  } while (0);
 
+
+C<OSSL_TRACE1()>, ... C<OSSL_TRACE9()> are one-shot macros which essentially wrap
+a single BIO_printf() into a tracing group.
+
+The call OSSL_TRACEn(category, format, arg1, ..., argN) expands to:
+
+  OSSL_TRACE_BEGIN(category) {
+    BIO_printf(trc_out, format, arg1, ..., argN)
+  } OSSL_TRACE_END(category)
+
 =head1 NOTES
 
 It is advisable to always check that a trace type is enabled with
@@ -110,10 +157,11 @@ OSSL_trace_enabled() before generating any output, for example:
         OSSL_trace_end(OSSL_TRACE_CATEGORY_TLS, trace);
     }
 
-=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:
 
@@ -132,7 +180,7 @@ nothing.
 =item *
 
 the convenience macros are defined to produce dead code.
-For example, take this example from L</Convenience Macros> above:
+For example, take this example from L</Macros> section above:
 
  OSSL_TRACE_BEGIN(TLS) {