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 3df9b5a51e9941d6065dfe570125a6e18c08828b..90a6350bebae5ac512b47a1f6435c768a2025ae5 100644 (file)
--- a/crypto/trace.c
+++ b/crypto/trace.c
@@ -473,7 +473,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 f9c9dffd8c6a8ae1afa650a608ddc6b32ed56886..bad5b15153539f58428745bd055111c82ce1f921 100644 (file)
--- a/doc/man3/OSSL_trace_enabled.pod
+++ b/doc/man3/OSSL_trace_enabled.pod
@@ -88,9 +88,10 @@ but rather uses a set of convenience macros, see the L</Macros> section below.
 OSSL_trace_enabled() can be used to check if tracing for the given
 I<category> is enabled.
 
-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.
 
@@ -187,6 +188,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.