1OSSL_TRACE_ENABLED(3ossl)           OpenSSL          OSSL_TRACE_ENABLED(3ossl)
2
3
4

NAME

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

SYNOPSIS

13        #include <openssl/trace.h>
14
15        int OSSL_trace_enabled(int category);
16
17        BIO *OSSL_trace_begin(int category);
18        void OSSL_trace_end(int category, BIO *channel);
19
20        /* 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
31        /* 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
37        /* check whether a trace category is enabled */
38        if (OSSL_TRACE_ENABLED(category)) {
39            ...
40        }
41

DESCRIPTION

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
47       If tracing is enabled (see "NOTES" below), these functions are used to
48       generate free text tracing output.
49
50       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
56       Tracing for a specific category is enabled if a so called trace channel
57       is attached to it. A trace channel is simply a BIO object to which the
58       application can write its trace output.
59
60       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(), or by providing a callback routine using
63       OSSL_trace_set_callback().  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
68       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
76       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
80   Functions
81       OSSL_trace_enabled() can be used to check if tracing for the given
82       category is enabled.
83
84       OSSL_trace_begin() is used to starts a tracing section, and get the
85       channel for the given category in form of a BIO.  This BIO can only be
86       used for output.
87
88       OSSL_trace_end() is used to end a tracing section.
89
90       Using OSSL_trace_begin() and OSSL_trace_end() to wrap tracing sections
91       is mandatory.  The result of trying to produce tracing output outside
92       of such sections is undefined.
93
94   Macros
95       There are a number of convenience macros defined, to make tracing easy
96       and consistent.
97
98       OSSL_TRACE_BEGIN() and OSSL_TRACE_END() reserve the BIO "trc_out" and
99       are used as follows to wrap a trace section:
100
101        OSSL_TRACE_BEGIN(TLS) {
102
103            BIO_fprintf(trc_out, ... );
104
105        } OSSL_TRACE_END(TLS);
106
107       This will normally expand to:
108
109        do {
110            BIO *trc_out = OSSL_trace_begin(OSSL_TRACE_CATEGORY_TLS);
111            if (trc_out != NULL) {
112                ...
113                BIO_fprintf(trc_out, ...);
114            }
115            OSSL_trace_end(OSSL_TRACE_CATEGORY_TLS, trc_out);
116        } while (0);
117
118       OSSL_TRACE_CANCEL() must be used before returning from or jumping out
119       of a trace section:
120
121        OSSL_TRACE_BEGIN(TLS) {
122
123            if (some_error) {
124                OSSL_TRACE_CANCEL(TLS);
125                goto err;
126            }
127            BIO_fprintf(trc_out, ... );
128
129        } OSSL_TRACE_END(TLS);
130
131       This will normally expand to:
132
133        do {
134            BIO *trc_out = OSSL_trace_begin(OSSL_TRACE_CATEGORY_TLS);
135            if (trc_out != NULL) {
136                if (some_error) {
137                    OSSL_trace_end(OSSL_TRACE_CATEGORY_TLS, trc_out);
138                    goto err;
139                }
140                BIO_fprintf(trc_out, ... );
141            }
142            OSSL_trace_end(OSSL_TRACE_CATEGORY_TLS, trc_out);
143        } while (0);
144
145       OSSL_TRACE() and OSSL_TRACE1(), OSSL_TRACE2(), ... OSSL_TRACE9() are
146       so-called one-shot macros:
147
148       The macro call "OSSL_TRACE(category, text)", produces literal text
149       trace output.
150
151       The macro call "OSSL_TRACEn(category, format, arg1, ..., argn)"
152       produces printf-style trace output with n format field arguments
153       (n=1,...,9).  It expands to:
154
155        OSSL_TRACE_BEGIN(category) {
156            BIO_printf(trc_out, format, arg1, ..., argN)
157        } OSSL_TRACE_END(category)
158
159       Internally, all one-shot macros are implemented using a generic
160       OSSL_TRACEV() macro, since C90 does not support variadic macros. This
161       helper macro has a rather weird synopsis and should not be used
162       directly.
163
164       The OSSL_TRACE_ENABLED() macro can be used to conditionally execute
165       some code only if a specific trace category is enabled.  In some
166       situations this is simpler than entering a trace section using
167       OSSL_TRACE_BEGIN() and OSSL_TRACE_END().  For example, the code
168
169        if (OSSL_TRACE_ENABLED(TLS)) {
170            ...
171        }
172
173       expands to
174
175        if (OSSL_trace_enabled(OSSL_TRACE_CATEGORY_TLS) {
176            ...
177        }
178

NOTES

180       If producing the trace output requires carrying out auxiliary
181       calculations, this auxiliary code should be placed inside a conditional
182       block which is executed only if the trace category is enabled.
183
184       The most natural way to do this is to place the code inside the trace
185       section itself because it already introduces such a conditional block.
186
187        OSSL_TRACE_BEGIN(TLS) {
188            int var = do_some_auxiliary_calculation();
189
190            BIO_printf(trc_out, "var = %d\n", var);
191
192        } OSSL_TRACE_END(TLS);
193
194       In some cases it is more advantageous to use a simple conditional group
195       instead of a trace section. This is the case if calculations and
196       tracing happen in different locations of the code, or if the
197       calculations are so time consuming that placing them inside a
198       (critical) trace section would create too much contention.
199
200        if (OSSL_TRACE_ENABLED(TLS)) {
201            int var = do_some_auxiliary_calculation();
202
203            OSSL_TRACE1("var = %d\n", var);
204        }
205
206       Note however that premature optimization of tracing code is in general
207       futile and it's better to keep the tracing code as simple as possible.
208       Because most often the limiting factor for the application's speed is
209       the time it takes to print the trace output, not to calculate it.
210
211   Configure Tracing
212       By default, the OpenSSL library is built with tracing disabled. To use
213       the tracing functionality documented here, it is therefore necessary to
214       configure and build OpenSSL with the 'enable-trace' option.
215
216       When the library is built with tracing disabled:
217
218       •   The macro OPENSSL_NO_TRACE is defined in <openssl/opensslconf.h>.
219
220       •   all functions are still present, but OSSL_trace_enabled() will
221           always report the categories as disabled, and all other functions
222           will do nothing.
223
224       •   the convenience macros are defined to produce dead code.  For
225           example, take this example from "Macros" section above:
226
227            OSSL_TRACE_BEGIN(TLS) {
228
229                if (condition) {
230                    OSSL_TRACE_CANCEL(TLS);
231                    goto err;
232                }
233                BIO_fprintf(trc_out, ... );
234
235            } OSSL_TRACE_END(TLS);
236
237           When the tracing API isn't operational, that will expand to:
238
239            do {
240                BIO *trc_out = NULL;
241                if (0) {
242                    if (condition) {
243                        ((void)0);
244                        goto err;
245                    }
246                    BIO_fprintf(trc_out, ... );
247                }
248            } while (0);
249

RETURN VALUES

251       OSSL_trace_enabled() returns 1 if tracing for the given type is
252       operational and enabled, otherwise 0.
253
254       OSSL_trace_begin() returns a BIO pointer if the given type is enabled,
255       otherwise NULL.
256

HISTORY

258       The OpenSSL Tracing API was added in OpenSSL 3.0.
259
261       Copyright 2019-2021 The OpenSSL Project Authors. All Rights Reserved.
262
263       Licensed under the Apache License 2.0 (the "License").  You may not use
264       this file except in compliance with the License.  You can obtain a copy
265       in the file LICENSE in the source distribution or at
266       <https://www.openssl.org/source/license.html>.
267
268
269
2703.0.5                             2022-11-01         OSSL_TRACE_ENABLED(3ossl)
Impressum