5 OSSL_trace_enabled, OSSL_trace_begin, OSSL_trace_end
10 #include <openssl/trace.h>
12 int OSSL_trace_enabled(int category);
14 BIO *OSSL_trace_begin(int category);
15 void OSSL_trace_end(int category, BIO *channel);
19 The functions described here are mainly interesting for those who provide
20 OpenSSL functionality, either in OpenSSL itself or in engine modules
23 If tracing is enabled (see L</NOTES> below), these functions are used to
24 generate free text tracing output.
26 The tracing output is divided into types which are enabled
27 individually by the application.
28 The tracing types are described in detail in
29 L<OSSL_trace_set_callback(3)/Trace types>.
30 The fallback type C<OSSL_TRACE_CATEGORY_ANY> should I<not> be used
31 with the functions described here.
35 OSSL_trace_enabled() can be used to check if tracing for the given
36 C<category> is enabled.
38 OSSL_trace_begin() is used to starts a tracing section, and get the
39 channel for the given C<category> in form of a BIO.
40 This BIO can only be used for output.
42 OSSL_trace_end() is used to end a tracing section.
44 Using OSSL_trace_begin() and OSSL_trace_end() to wrap tracing sections
46 The result of trying to produce tracing output outside of such
47 sections is undefined.
49 =head2 Convenience Macros
51 There are a number of convenience macros defined, to make tracing
54 C<OSSL_TRACE_BEGIN(category)> and C<OSSL_TRACE_END(category)> reserve
55 the B<BIO> C<trc_out> and are used as follows to wrap a trace section:
57 OSSL_TRACE_BEGIN(TLS) {
59 BIO_fprintf(trc_out, ... );
61 } OSSL_TRACE_END(TLS);
63 This will normally expands to:
66 BIO *trc_out = OSSL_trace_begin(OSSL_TRACE_CATEGORY_TLS);
67 if (trc_out != NULL) {
69 BIO_fprintf(trc_out, ...);
71 OSSL_trace_end(OSSL_TRACE_CATEGORY_TLS, trc_out);
74 C<OSSL_TRACE_CANCEL(category)> must be used before returning from or
75 jumping out of a trace section:
77 OSSL_TRACE_BEGIN(TLS) {
80 OSSL_TRACE_CANCEL(TLS);
83 BIO_fprintf(trc_out, ... );
85 } OSSL_TRACE_END(TLS);
87 This will normally expand to:
90 BIO *trc_out = OSSL_trace_begin(OSSL_TRACE_CATEGORY_TLS);
91 if (trc_out != NULL) {
93 OSSL_trace_end(OSSL_TRACE_CATEGORY_TLS, trc_out);
96 BIO_fprintf(trc_out, ... );
98 OSSL_trace_end(OSSL_TRACE_CATEGORY_TLS, trc_out);
103 It is advisable to always check that a trace type is enabled with
104 OSSL_trace_enabled() before generating any output, for example:
106 if (OSSL_trace_enabled(OSSL_TRACE_CATEGORY_TLS)) {
107 BIO *trace = OSSL_trace_begin(OSSL_TRACE_CATEGORY_TLS);
108 BIO_printf(trace, "FOO %d\n", somevalue);
109 BIO_dump(trace, somememory, somememory_l);
110 OSSL_trace_end(OSSL_TRACE_CATEGORY_TLS, trace);
113 =head2 Configure Tracing
115 By default, the OpenSSL library is built with tracing disabled. To
116 use the tracing functionality documented here, it is therefore
117 necessary to configure and build OpenSSL with the 'enable-trace' option.
119 When the library is built with tracing disabled:
125 The macro C<OPENSSL_NO_TRACE> is defined in C<openssl/opensslconf.h>.
129 all functions are still present, bu OSSL_trace_enabled() will always
130 report the categories as disabled, and all other functions will do
135 the convenience macros are defined to produce dead code.
136 For example, take this example from L</Convenience Macros> above:
138 OSSL_TRACE_BEGIN(TLS) {
141 OSSL_TRACE_CANCEL(TLS);
144 BIO_fprintf(trc_out, ... );
146 } OSSL_TRACE_END(TLS);
148 When the tracing API isn't operational, that will expand to:
157 BIO_fprintf(trc_out, ... );
165 OSSL_trace_enabled() returns 1 if tracing for the given B<type> is
166 operational and enabled, otherwise 0.
168 OSSL_trace_begin() returns a C<BIO *> if the given B<type> is enabled,
173 The OpenSSL Tracing API was added ino OpenSSL 3.0.0.
177 Copyright 2019 The OpenSSL Project Authors. All Rights Reserved.
179 Licensed under the Apache License 2.0 (the "License"). You may not use
180 this file except in compliance with the License. You can obtain a copy
181 in the file LICENSE in the source distribution or at
182 L<https://www.openssl.org/source/license.html>.