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)

(cherry picked from commit 72d3e9bac41302e5bc00db1bef014b0ca810d2cf)

diff --git a/crypto/trace.c b/crypto/trace.c
index dc308d819d015c0ef164666226d5fd0d5089a49f..e7a5966f369d13a24b8e9bfc9c7257bd323a8375 100644 (file)
--- a/crypto/trace.c
+++ b/crypto/trace.c
@@ -474,7 +474,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 fcbea3cbf61b6b923dfa43bab028f10fe0ee6f18..ee0e436e69b90d118134d88650aeb187a9b57205 100644 (file)
--- a/doc/man3/OSSL_trace_enabled.pod
+++ b/doc/man3/OSSL_trace_enabled.pod
@@ -90,9 +90,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.
 
@@ -189,6 +190,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.