TRACE: automatically respect disabled categories

by fixing OSSL_trace_begin() to return NULL when given category is not enabled

Reviewed-by: Tom Cosgrove <tom.cosgrove@arm.com>
Reviewed-by: Tomas Mraz <tomas@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/25652)

diff --git a/crypto/trace.c b/crypto/trace.c
index 51387641de948c88c01f80c97df2323f2a419e3b..3e10d91fc26386573d8f9f8d3f80c31bf98ee2bb 100644 (file)
--- a/crypto/trace.c
+++ b/crypto/trace.c
@@ -475,7 +475,7 @@ BIO *OSSL_trace_begin(int category)
     char *prefix = NULL;
 
     category = ossl_trace_get_category(category);
-    if (category < 0)
+    if (category < 0 || !OSSL_trace_enabled(category))
         return NULL;
 
     channel = trace_channels[category].bio;

diff --git a/doc/man3/OSSL_trace_enabled.pod b/doc/man3/OSSL_trace_enabled.pod
index da78eba234bcb182603214e2cee995e0329d92b1..987dd7f91af21881ac00a4a753002bbaa1dd6ab0 100644 (file)
--- a/doc/man3/OSSL_trace_enabled.pod
+++ b/doc/man3/OSSL_trace_enabled.pod
@@ -97,9 +97,10 @@ 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() is used to start a tracing section,
+and get the channel for the given I<category> in form of a BIO.
 This BIO can only be used for output.
+The pointer returned is NULL if the category is invalid or not enabled.
 
 OSSL_trace_end() is used to end a tracing section.
 
@@ -211,6 +212,9 @@ expands to
 
 =head1 NOTES
 
+It is not needed to guard trace output function calls like
+I<OSSL_TRACE(category, ...)> by I<OSSL_TRACE_ENABLED(category)>.
+
 If producing the trace output requires carrying out auxiliary calculations,
 this auxiliary code should be placed inside a conditional block which is
 executed only if the trace category is enabled.