5 OSSL_trace_enabled, OSSL_trace_begin, OSSL_trace_end,
6 OSSL_TRACE_BEGIN, OSSL_TRACE_END, OSSL_TRACE_CANCEL,
7 OSSL_TRACE, OSSL_TRACE1, OSSL_TRACE2, OSSL_TRACE3, OSSL_TRACE4,
8 OSSL_TRACE5, OSSL_TRACE6, OSSL_TRACE7, OSSL_TRACE8, OSSL_TRACE9,
17 #include <openssl/trace.h>
19 int OSSL_trace_enabled(int category);
21 BIO *OSSL_trace_begin(int category);
22 void OSSL_trace_end(int category, BIO *channel);
24 /* trace group macros */
25 OSSL_TRACE_BEGIN(category) {
28 /* Leave trace group prematurely in case of an error */
29 OSSL_TRACE_CANCEL(category);
33 } OSSL_TRACE_END(category);
35 /* one-shot trace macros */
36 OSSL_TRACE1(category, format, arg1)
37 OSSL_TRACE2(category, format, arg1, arg2)
39 OSSL_TRACE9(category, format, arg1, ..., arg9)
41 /* check whether a trace category is enabled */
42 if (OSSL_TRACE_ENABLED(category)) {
48 The functions described here are mainly interesting for those who provide
49 OpenSSL functionality, either in OpenSSL itself or in engine modules
52 If tracing is enabled (see L</NOTES> below), these functions are used to
53 generate free text tracing output.
55 The tracing output is divided into types which are enabled
56 individually by the application.
57 The tracing types are described in detail in
58 L<OSSL_trace_set_callback(3)/Trace types>.
59 The fallback type B<OSSL_TRACE_CATEGORY_ALL> should I<not> be used
60 with the functions described here.
62 Tracing for a specific category is enabled if a so called
63 I<trace channel> is attached to it. A trace channel is simply a
64 BIO object to which the application can write its trace output.
66 The application has two different ways of registering a trace channel,
67 either by directly providing a BIO object using OSSL_trace_set_channel(),
68 or by providing a callback routine using OSSL_trace_set_callback().
69 The latter is wrapped internally by a dedicated BIO object, so for the
70 tracing code both channel types are effectively indistinguishable.
71 We call them a I<simple trace channel> and a I<callback trace channel>,
74 To produce trace output, it is necessary to obtain a pointer to the
75 trace channel (i.e., the BIO object) using OSSL_trace_begin(), write
76 to it using arbitrary BIO output routines, and finally releases the
77 channel using OSSL_trace_end(). The OSSL_trace_begin()/OSSL_trace_end()
78 calls surrounding the trace output create a group, which acts as a
79 critical section (guarded by a mutex) to ensure that the trace output
80 of different threads does not get mixed up.
82 The tracing code normally does not call OSSL_trace_{begin,end}() directly,
83 but rather uses a set of convenience macros, see the L</Macros> section below.
88 OSSL_trace_enabled() can be used to check if tracing for the given
89 I<category> is enabled.
91 OSSL_trace_begin() is used to starts a tracing section, and get the
92 channel for the given I<category> in form of a BIO.
93 This BIO can only be used for output.
95 OSSL_trace_end() is used to end a tracing section.
97 Using OSSL_trace_begin() and OSSL_trace_end() to wrap tracing sections
99 The result of trying to produce tracing output outside of such
100 sections is undefined.
104 There are a number of convenience macros defined, to make tracing
107 OSSL_TRACE_BEGIN() and OSSL_TRACE_END() reserve the B<BIO> C<trc_out> and are
108 used as follows to wrap a trace section:
110 OSSL_TRACE_BEGIN(TLS) {
112 BIO_fprintf(trc_out, ... );
114 } OSSL_TRACE_END(TLS);
116 This will normally expand to:
119 BIO *trc_out = OSSL_trace_begin(OSSL_TRACE_CATEGORY_TLS);
120 if (trc_out != NULL) {
122 BIO_fprintf(trc_out, ...);
124 OSSL_trace_end(OSSL_TRACE_CATEGORY_TLS, trc_out);
127 OSSL_TRACE_CANCEL() must be used before returning from or jumping out of a
130 OSSL_TRACE_BEGIN(TLS) {
133 OSSL_TRACE_CANCEL(TLS);
136 BIO_fprintf(trc_out, ... );
138 } OSSL_TRACE_END(TLS);
140 This will normally expand to:
143 BIO *trc_out = OSSL_trace_begin(OSSL_TRACE_CATEGORY_TLS);
144 if (trc_out != NULL) {
146 OSSL_trace_end(OSSL_TRACE_CATEGORY_TLS, trc_out);
149 BIO_fprintf(trc_out, ... );
151 OSSL_trace_end(OSSL_TRACE_CATEGORY_TLS, trc_out);
155 OSSL_TRACE() and OSSL_TRACE1(), OSSL_TRACE2(), ... OSSL_TRACE9() are
156 so-called one-shot macros:
158 The macro call C<OSSL_TRACE(category, text)>, produces literal text trace output.
160 The macro call C<OSSL_TRACEn(category, format, arg1, ..., argn)> produces
161 printf-style trace output with n format field arguments (n=1,...,9).
164 OSSL_TRACE_BEGIN(category) {
165 BIO_printf(trc_out, format, arg1, ..., argN)
166 } OSSL_TRACE_END(category)
168 Internally, all one-shot macros are implemented using a generic OSSL_TRACEV()
169 macro, since C90 does not support variadic macros. This helper macro has a rather
170 weird synopsis and should not be used directly.
172 The OSSL_TRACE_ENABLED() macro can be used to conditionally execute some code
173 only if a specific trace category is enabled.
174 In some situations this is simpler than entering a trace section using
175 OSSL_TRACE_BEGIN() and OSSL_TRACE_END().
176 For example, the code
178 if (OSSL_TRACE_ENABLED(TLS)) {
184 if (OSSL_trace_enabled(OSSL_TRACE_CATEGORY_TLS) {
190 If producing the trace output requires carrying out auxiliary calculations,
191 this auxiliary code should be placed inside a conditional block which is
192 executed only if the trace category is enabled.
194 The most natural way to do this is to place the code inside the trace section
195 itself because it already introduces such a conditional block.
197 OSSL_TRACE_BEGIN(TLS) {
198 int var = do_some_auxiliary_calculation();
200 BIO_printf(trc_out, "var = %d\n", var);
202 } OSSL_TRACE_END(TLS);
204 In some cases it is more advantageous to use a simple conditional group instead
205 of a trace section. This is the case if calculations and tracing happen in
206 different locations of the code, or if the calculations are so time consuming
207 that placing them inside a (critical) trace section would create too much
210 if (OSSL_TRACE_ENABLED(TLS)) {
211 int var = do_some_auxiliary_calculation();
213 OSSL_TRACE1("var = %d\n", var);
216 Note however that premature optimization of tracing code is in general futile
217 and it's better to keep the tracing code as simple as possible.
218 Because most often the limiting factor for the application's speed is the time
219 it takes to print the trace output, not to calculate it.
221 =head2 Configure Tracing
223 By default, the OpenSSL library is built with tracing disabled. To
224 use the tracing functionality documented here, it is therefore
225 necessary to configure and build OpenSSL with the 'enable-trace' option.
227 When the library is built with tracing disabled:
233 The macro B<OPENSSL_NO_TRACE> is defined in F<< <openssl/opensslconf.h> >>.
237 all functions are still present, bu OSSL_trace_enabled() will always
238 report the categories as disabled, and all other functions will do
243 the convenience macros are defined to produce dead code.
244 For example, take this example from L</Macros> section above:
246 OSSL_TRACE_BEGIN(TLS) {
249 OSSL_TRACE_CANCEL(TLS);
252 BIO_fprintf(trc_out, ... );
254 } OSSL_TRACE_END(TLS);
256 When the tracing API isn't operational, that will expand to:
265 BIO_fprintf(trc_out, ... );
273 OSSL_trace_enabled() returns 1 if tracing for the given I<type> is
274 operational and enabled, otherwise 0.
276 OSSL_trace_begin() returns a B<BIO> pointer if the given I<type> is enabled,
281 The OpenSSL Tracing API was added ino OpenSSL 3.0.
285 Copyright 2019 The OpenSSL Project Authors. All Rights Reserved.
287 Licensed under the Apache License 2.0 (the "License"). You may not use
288 this file except in compliance with the License. You can obtain a copy
289 in the file LICENSE in the source distribution or at
290 L<https://www.openssl.org/source/license.html>.