1OSSL_TRACE_ENABLED(3ossl) OpenSSL OSSL_TRACE_ENABLED(3ossl)
2
6 OSSL_trace_enabled, OSSL_trace_begin, OSSL_trace_end, OSSL_TRACE_BEGIN,
7 OSSL_TRACE_END, OSSL_TRACE_CANCEL, OSSL_TRACE, OSSL_TRACE1,
8 OSSL_TRACE2, OSSL_TRACE3, OSSL_TRACE4, OSSL_TRACE5, OSSL_TRACE6,
9 OSSL_TRACE7, OSSL_TRACE8, OSSL_TRACE9, OSSL_TRACEV, OSSL_TRACE_ENABLED
10 - OpenSSL Tracing API
11
13 #include <openssl/trace.h>
14 int OSSL_trace_enabled(int category);
16 BIO *OSSL_trace_begin(int category);
18 void OSSL_trace_end(int category, BIO *channel);
19 /* trace group macros */
21 OSSL_TRACE_BEGIN(category) {
22 ...
23 if (some_error) {
24 /* Leave trace group prematurely in case of an error */
25 OSSL_TRACE_CANCEL(category);
26 goto err;
27 }
28 ...
29 } OSSL_TRACE_END(category);
30 /* one-shot trace macros */
32 OSSL_TRACE1(category, format, arg1)
33 OSSL_TRACE2(category, format, arg1, arg2)
34 ...
35 OSSL_TRACE9(category, format, arg1, ..., arg9)
36 /* check whether a trace category is enabled */
38 if (OSSL_TRACE_ENABLED(category)) {
39 ...
40 }
41
43 The functions described here are mainly interesting for those who
44 provide OpenSSL functionality, either in OpenSSL itself or in engine
45 modules or similar.
46 If the tracing facility is enabled (see "Configure Tracing" below),
48 these functions are used to generate free text tracing output.
49 The tracing output is divided into types which are enabled individually
51 by the application. The tracing types are described in detail in
52 "Trace types" in OSSL_trace_set_callback(3). The fallback type
53 OSSL_TRACE_CATEGORY_ALL should not be used with the functions described
54 here.
55 Tracing for a specific category is enabled at run-time if a so-called
57 trace channel is attached to it. A trace channel is simply a BIO object
58 to which the application can write its trace output.
59 The application has two different ways of registering a trace channel,
61 either by directly providing a BIO object using
62 OSSL_trace_set_channel(3), or by providing a callback routine using
63 OSSL_trace_set_callback(3). The latter is wrapped internally by a
64 dedicated BIO object, so for the tracing code both channel types are
65 effectively indistinguishable. We call them a simple trace channel and
66 a callback trace channel, respectively.
67 To produce trace output, it is necessary to obtain a pointer to the
69 trace channel (i.e., the BIO object) using OSSL_trace_begin(), write to
70 it using arbitrary BIO output routines, and finally releases the
71 channel using OSSL_trace_end(). The OSSL_trace_begin()/OSSL_trace_end()
72 calls surrounding the trace output create a group, which acts as a
73 critical section (guarded by a mutex) to ensure that the trace output
74 of different threads does not get mixed up.
75 The tracing code normally does not call OSSL_trace_{begin,end}()
77 directly, but rather uses a set of convenience macros, see the "Macros"
78 section below.
79 Functions
81 OSSL_trace_enabled() can be used to check if tracing for the given
82 category is enabled, i.e., if the tracing facility has been statically
83 enabled (see "Configure Tracing" below) and a trace channel has been
84 registered using OSSL_trace_set_channel(3) or
85 OSSL_trace_set_callback(3).
86 OSSL_trace_begin() is used to starts a tracing section, and get the
88 channel for the given category in form of a BIO. This BIO can only be
89 used for output.
90 OSSL_trace_end() is used to end a tracing section.
92 Using OSSL_trace_begin() and OSSL_trace_end() to wrap tracing sections
94 is mandatory. The result of trying to produce tracing output outside
95 of such sections is undefined.
96 Macros
98 There are a number of convenience macros defined, to make tracing easy
99 and consistent.
100 OSSL_TRACE_BEGIN() and OSSL_TRACE_END() reserve the BIO "trc_out" and
102 are used as follows to wrap a trace section:
103 OSSL_TRACE_BEGIN(TLS) {
105 BIO_printf(trc_out, ... );
107 } OSSL_TRACE_END(TLS);
109 This will normally expand to:
111 do {
113 BIO *trc_out = OSSL_trace_begin(OSSL_TRACE_CATEGORY_TLS);
114 if (trc_out != NULL) {
115 ...
116 BIO_printf(trc_out, ...);
117 }
118 OSSL_trace_end(OSSL_TRACE_CATEGORY_TLS, trc_out);
119 } while (0);
120 OSSL_TRACE_CANCEL() must be used before returning from or jumping out
122 of a trace section:
123 OSSL_TRACE_BEGIN(TLS) {
125 if (some_error) {
127 OSSL_TRACE_CANCEL(TLS);
128 goto err;
129 }
130 BIO_printf(trc_out, ... );
131 } OSSL_TRACE_END(TLS);
133 This will normally expand to:
135 do {
137 BIO *trc_out = OSSL_trace_begin(OSSL_TRACE_CATEGORY_TLS);
138 if (trc_out != NULL) {
139 if (some_error) {
140 OSSL_trace_end(OSSL_TRACE_CATEGORY_TLS, trc_out);
141 goto err;
142 }
143 BIO_printf(trc_out, ... );
144 }
145 OSSL_trace_end(OSSL_TRACE_CATEGORY_TLS, trc_out);
146 } while (0);
147 OSSL_TRACE() and OSSL_TRACE1(), OSSL_TRACE2(), ... OSSL_TRACE9() are
149 so-called one-shot macros:
150 The macro call "OSSL_TRACE(category, text)", produces literal text
152 trace output.
153 The macro call "OSSL_TRACEn(category, format, arg1, ..., argn)"
155 produces printf-style trace output with n format field arguments
156 (n=1,...,9). It expands to:
157 OSSL_TRACE_BEGIN(category) {
159 BIO_printf(trc_out, format, arg1, ..., argN)
160 } OSSL_TRACE_END(category)
161 Internally, all one-shot macros are implemented using a generic
163 OSSL_TRACEV() macro, since C90 does not support variadic macros. This
164 helper macro has a rather weird synopsis and should not be used
165 directly.
166 The OSSL_TRACE_ENABLED() macro can be used to conditionally execute
168 some code only if a specific trace category is enabled. In some
169 situations this is simpler than entering a trace section using
170 OSSL_TRACE_BEGIN() and OSSL_TRACE_END(). For example, the code
171 if (OSSL_TRACE_ENABLED(TLS)) {
173 ...
174 }
175 expands to
177 if (OSSL_trace_enabled(OSSL_TRACE_CATEGORY_TLS) {
179 ...
180 }
181
183 If producing the trace output requires carrying out auxiliary
184 calculations, this auxiliary code should be placed inside a conditional
185 block which is executed only if the trace category is enabled.
186 The most natural way to do this is to place the code inside the trace
188 section itself because it already introduces such a conditional block.
189 OSSL_TRACE_BEGIN(TLS) {
191 int var = do_some_auxiliary_calculation();
192 BIO_printf(trc_out, "var = %d\n", var);
194 } OSSL_TRACE_END(TLS);
196 In some cases it is more advantageous to use a simple conditional group
198 instead of a trace section. This is the case if calculations and
199 tracing happen in different locations of the code, or if the
200 calculations are so time consuming that placing them inside a
201 (critical) trace section would create too much contention.
202 if (OSSL_TRACE_ENABLED(TLS)) {
204 int var = do_some_auxiliary_calculation();
205 OSSL_TRACE1("var = %d\n", var);
207 }
208 Note however that premature optimization of tracing code is in general
210 futile and it's better to keep the tracing code as simple as possible.
211 Because most often the limiting factor for the application's speed is
212 the time it takes to print the trace output, not to calculate it.
213 Configure Tracing
215 By default, the OpenSSL library is built with tracing disabled. To use
216 the tracing functionality documented here, it is therefore necessary to
217 configure and build OpenSSL with the 'enable-trace' option.
218 When the library is built with tracing disabled:
220 • The macro OPENSSL_NO_TRACE is defined in <openssl/opensslconf.h>.
222 • all functions are still present, but OSSL_trace_enabled() will
224 always report the categories as disabled, and all other functions
225 will do nothing.
226 • the convenience macros are defined to produce dead code. For
228 example, take this example from "Macros" section above:
229 OSSL_TRACE_BEGIN(TLS) {
231 if (condition) {
233 OSSL_TRACE_CANCEL(TLS);
234 goto err;
235 }
236 BIO_printf(trc_out, ... );
237 } OSSL_TRACE_END(TLS);
239 When the tracing API isn't operational, that will expand to:
241 do {
243 BIO *trc_out = NULL;
244 if (0) {
245 if (condition) {
246 ((void)0);
247 goto err;
248 }
249 BIO_printf(trc_out, ... );
250 }
251 } while (0);
252
254 OSSL_trace_enabled() returns 1 if tracing for the given type is
255 operational and enabled, otherwise 0.
256 OSSL_trace_begin() returns a BIO pointer if the given type is enabled,
258 otherwise NULL.
259
261 OSSL_trace_set_channel(3), OSSL_trace_set_callback(3)
262
264 The OpenSSL Tracing API was added in OpenSSL 3.0.
265
267 Copyright 2019-2022 The OpenSSL Project Authors. All Rights Reserved.
268 Licensed under the Apache License 2.0 (the "License"). You may not use
270 this file except in compliance with the License. You can obtain a copy
271 in the file LICENSE in the source distribution or at
272 <https://www.openssl.org/source/license.html>.
2733.1.1 2023-08-31 OSSL_TRACE_ENABLED(3ossl)