Debian Codegraph @

upstream/debian-unstable/man3/OSSL_trace_enabled.3ssl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "OSSL_TRACE_ENABLED 3SSL"
58 .TH OSSL_TRACE_ENABLED 3SSL 2026-04-07 3.6.2 OpenSSL
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 OSSL_trace_enabled, OSSL_trace_begin, OSSL_trace_end,
65 OSSL_TRACE_BEGIN, OSSL_TRACE_END, OSSL_TRACE_CANCEL,
66 OSSL_TRACE, OSSL_TRACE1, OSSL_TRACE2, OSSL_TRACE3, OSSL_TRACE4,
67 OSSL_TRACE5, OSSL_TRACE6, OSSL_TRACE7, OSSL_TRACE8, OSSL_TRACE9,
68 OSSL_TRACEV,
69 OSSL_TRACE_STRING, OSSL_TRACE_STRING_MAX, OSSL_trace_string,
70 OSSL_TRACE_ENABLED
71 \&\- OpenSSL Tracing API
72 .SH SYNOPSIS
73 .IX Header "SYNOPSIS"
74 .Vb 1
75 \& #include <openssl/trace.h>
76 \&
77 \& int OSSL_trace_enabled(int category);
78 \&
79 \& BIO *OSSL_trace_begin(int category);
80 \& void OSSL_trace_end(int category, BIO *channel);
81 \&
82 \& /* trace group macros */
83 \& OSSL_TRACE_BEGIN(category) {
84 \& ...
85 \& if (some_error) {
86 \& /* Leave trace group prematurely in case of an error */
87 \& OSSL_TRACE_CANCEL(category);
88 \& goto err;
89 \& }
90 \& ...
91 \& } OSSL_TRACE_END(category);
92 \&
93 \& /* one\-shot trace macros */
94 \& OSSL_TRACE(category, text)
95 \& OSSL_TRACE1(category, format, arg1)
96 \& OSSL_TRACE2(category, format, arg1, arg2)
97 \& ...
98 \& OSSL_TRACE9(category, format, arg1, ..., arg9)
99 \& OSSL_TRACE_STRING(category, text, full, data, len)
100 \&
101 \& #define OSSL_TRACE_STRING_MAX 80
102 \& int OSSL_trace_string(BIO *out, int text, int full,
103 \& const unsigned char *data, size_t size);
104 \&
105 \& /* check whether a trace category is enabled */
106 \& if (OSSL_TRACE_ENABLED(category)) {
107 \& ...
108 \& }
109 .Ve
110 .SH DESCRIPTION
111 .IX Header "DESCRIPTION"
112 The functions described here are mainly interesting for those who provide
113 OpenSSL functionality, either in OpenSSL itself or in engine modules
114 or similar.
115 .PP
116 If the tracing facility is enabled (see "Configure Tracing" below),
117 these functions are used to generate free text tracing output.
118 .PP
119 The tracing output is divided into types which are enabled
120 individually by the application.
121 The tracing types are described in detail in
122 "Trace types" in \fBOSSL_trace_set_callback\fR\|(3).
123 The fallback type \fBOSSL_TRACE_CATEGORY_ALL\fR should \fInot\fR be used
124 with the functions described here.
125 .PP
126 Tracing for a specific category is enabled at run-time if a so-called
127 \&\fItrace channel\fR is attached to it. A trace channel is simply a
128 BIO object to which the application can write its trace output.
129 .PP
130 The application has two different ways of registering a trace channel,
131 either by directly providing a BIO object using \fBOSSL_trace_set_channel\fR\|(3),
132 or by providing a callback routine using \fBOSSL_trace_set_callback\fR\|(3).
133 The latter is wrapped internally by a dedicated BIO object, so for the
134 tracing code both channel types are effectively indistinguishable.
135 We call them a \fIsimple trace channel\fR and a \fIcallback trace channel\fR,
136 respectively.
137 .PP
138 To produce trace output, it is necessary to obtain a pointer to the
139 trace channel (i.e., the BIO object) using \fBOSSL_trace_begin()\fR, write
140 to it using arbitrary BIO output routines, and finally releases the
141 channel using \fBOSSL_trace_end()\fR. The \fBOSSL_trace_begin()\fR/\fBOSSL_trace_end()\fR
142 calls surrounding the trace output create a group, which acts as a
143 critical section (guarded by a mutex) to ensure that the trace output
144 of different threads does not get mixed up.
145 .PP
146 The tracing code normally does not call OSSL_trace_{begin,end}() directly,
147 but rather uses a set of convenience macros, see the "Macros" section below.
148 .SS Functions
149 .IX Subsection "Functions"
150 \&\fBOSSL_trace_enabled()\fR can be used to check if tracing for the given
151 \&\fIcategory\fR is enabled, i.e., if the tracing facility has been statically
152 enabled (see "Configure Tracing" below) and a trace channel has been
153 registered using \fBOSSL_trace_set_channel\fR\|(3) or \fBOSSL_trace_set_callback\fR\|(3).
154 .PP
155 \&\fBOSSL_trace_begin()\fR is used to start a tracing section,
156 and get the channel for the given \fIcategory\fR in form of a BIO.
157 This BIO can only be used for output.
158 The pointer returned is NULL if the category is invalid or not enabled.
159 .PP
160 \&\fBOSSL_trace_end()\fR is used to end a tracing section.
161 .PP
162 Using \fBOSSL_trace_begin()\fR and \fBOSSL_trace_end()\fR to wrap tracing sections
163 is \fImandatory\fR.
164 The result of trying to produce tracing output outside of such
165 sections is undefined.
166 .PP
167 \&\fBOSSL_trace_string()\fR outputs \fIdata\fR of length \fIsize\fR as a string on BIO \fIout\fR.
168 If \fItext\fR is 0, the function masks any included control characters apart from
169 newlines and makes sure for nonempty input that the output ends with a newline.
170 Unless \fIfull\fR is nonzero, the length is limited (with a suitable warning)
171 to \fBOSSL_TRACE_STRING_MAX\fR characters, which currently is 80.
172 .SS Macros
173 .IX Subsection "Macros"
174 There are a number of convenience macros defined, to make tracing
175 easy and consistent.
176 .PP
177 \&\fBOSSL_TRACE_BEGIN()\fR and \fBOSSL_TRACE_END()\fR reserve the \fBBIO\fR \f(CW\*(C`trc_out\*(C'\fR and are
178 used as follows to wrap a trace section:
179 .PP
180 .Vb 1
181 \& OSSL_TRACE_BEGIN(TLS) {
182 \&
183 \& BIO_printf(trc_out, ... );
184 \&
185 \& } OSSL_TRACE_END(TLS);
186 .Ve
187 .PP
188 This will normally expand to:
189 .PP
190 .Vb 8
191 \& do {
192 \& BIO *trc_out = OSSL_trace_begin(OSSL_TRACE_CATEGORY_TLS);
193 \& if (trc_out != NULL) {
194 \& ...
195 \& BIO_printf(trc_out, ...);
196 \& }
197 \& OSSL_trace_end(OSSL_TRACE_CATEGORY_TLS, trc_out);
198 \& } while (0);
199 .Ve
200 .PP
201 \&\fBOSSL_TRACE_CANCEL()\fR must be used before returning from or jumping out of a
202 trace section:
203 .PP
204 .Vb 1
205 \& OSSL_TRACE_BEGIN(TLS) {
206 \&
207 \& if (some_error) {
208 \& OSSL_TRACE_CANCEL(TLS);
209 \& goto err;
210 \& }
211 \& BIO_printf(trc_out, ... );
212 \&
213 \& } OSSL_TRACE_END(TLS);
214 .Ve
215 .PP
216 This will normally expand to:
217 .PP
218 .Vb 11
219 \& do {
220 \& BIO *trc_out = OSSL_trace_begin(OSSL_TRACE_CATEGORY_TLS);
221 \& if (trc_out != NULL) {
222 \& if (some_error) {
223 \& OSSL_trace_end(OSSL_TRACE_CATEGORY_TLS, trc_out);
224 \& goto err;
225 \& }
226 \& BIO_printf(trc_out, ... );
227 \& }
228 \& OSSL_trace_end(OSSL_TRACE_CATEGORY_TLS, trc_out);
229 \& } while (0);
230 .Ve
231 .PP
232 \&\fBOSSL_TRACE()\fR and \fBOSSL_TRACE1()\fR, \fBOSSL_TRACE2()\fR, ... \fBOSSL_TRACE9()\fR are
233 so-called one-shot macros:
234 .PP
235 The macro call \f(CW\*(C`OSSL_TRACE(category, text)\*(C'\fR, produces literal text trace output.
236 .PP
237 The macro call \f(CW\*(C`OSSL_TRACEn(category, format, arg1, ..., argn)\*(C'\fR produces
238 printf-style trace output with n format field arguments (n=1,...,9).
239 It expands to:
240 .PP
241 .Vb 3
242 \& OSSL_TRACE_BEGIN(category) {
243 \& BIO_printf(trc_out, format, arg1, ..., argN);
244 \& } OSSL_TRACE_END(category)
245 .Ve
246 .PP
247 Internally, all one-shot macros are implemented using a generic \fBOSSL_TRACEV()\fR
248 macro, since C90 does not support variadic macros. This helper macro has a rather
249 weird synopsis and should not be used directly.
250 .PP
251 The macro call \f(CW\*(C`OSSL_TRACE_STRING(category, text, full, data, len)\*(C'\fR
252 outputs \fIdata\fR of length \fIsize\fR as a string
253 if tracing for the given \fIcategory\fR is enabled.
254 It expands to:
255 .PP
256 .Vb 3
257 \& OSSL_TRACE_BEGIN(category) {
258 \& OSSL_trace_string(trc_out, text, full, data, len);
259 \& } OSSL_TRACE_END(category)
260 .Ve
261 .PP
262 The \fBOSSL_TRACE_ENABLED()\fR macro can be used to conditionally execute some code
263 only if a specific trace category is enabled.
264 In some situations this is simpler than entering a trace section using
265 \&\fBOSSL_TRACE_BEGIN()\fR and \fBOSSL_TRACE_END()\fR.
266 For example, the code
267 .PP
268 .Vb 3
269 \& if (OSSL_TRACE_ENABLED(TLS)) {
270 \& ...
271 \& }
272 .Ve
273 .PP
274 expands to
275 .PP
276 .Vb 3
277 \& if (OSSL_trace_enabled(OSSL_TRACE_CATEGORY_TLS) {
278 \& ...
279 \& }
280 .Ve
281 .SH NOTES
282 .IX Header "NOTES"
283 It is not needed to guard trace output function calls like
284 \&\fIOSSL_TRACE(category, ...)\fR by \fIOSSL_TRACE_ENABLED(category)\fR.
285 .PP
286 If producing the trace output requires carrying out auxiliary calculations,
287 this auxiliary code should be placed inside a conditional block which is
288 executed only if the trace category is enabled.
289 .PP
290 The most natural way to do this is to place the code inside the trace section
291 itself because it already introduces such a conditional block.
292 .PP
293 .Vb 2
294 \& OSSL_TRACE_BEGIN(TLS) {
295 \& int var = do_some_auxiliary_calculation();
296 \&
297 \& BIO_printf(trc_out, "var = %d\en", var);
298 \&
299 \& } OSSL_TRACE_END(TLS);
300 .Ve
301 .PP
302 In some cases it is more advantageous to use a simple conditional group instead
303 of a trace section. This is the case if calculations and tracing happen in
304 different locations of the code, or if the calculations are so time consuming
305 that placing them inside a (critical) trace section would create too much
306 contention.
307 .PP
308 .Vb 2
309 \& if (OSSL_TRACE_ENABLED(TLS)) {
310 \& int var = do_some_auxiliary_calculation();
311 \&
312 \& OSSL_TRACE1("var = %d\en", var);
313 \& }
314 .Ve
315 .PP
316 Note however that premature optimization of tracing code is in general futile
317 and it's better to keep the tracing code as simple as possible.
318 Because most often the limiting factor for the application's speed is the time
319 it takes to print the trace output, not to calculate it.
320 .SS "Configure Tracing"
321 .IX Subsection "Configure Tracing"
322 By default, the OpenSSL library is built with tracing disabled. To
323 use the tracing functionality documented here, it is therefore
324 necessary to configure and build OpenSSL with the 'enable\-trace' option.
325 .PP
326 When the library is built with tracing disabled:
327 .IP \(bu 4
328 The macro \fBOPENSSL_NO_TRACE\fR is defined in \fI<openssl/opensslconf.h>\fR.
329 .IP \(bu 4
330 all functions are still present, but \fBOSSL_trace_enabled()\fR will always
331 report the categories as disabled, and all other functions will do
332 nothing.
333 .IP \(bu 4
334 the convenience macros are defined to produce dead code.
335 For example, take this example from "Macros" section above:
336 .Sp
337 .Vb 1
338 \& OSSL_TRACE_BEGIN(TLS) {
339 \&
340 \& if (condition) {
341 \& OSSL_TRACE_CANCEL(TLS);
342 \& goto err;
343 \& }
344 \& BIO_printf(trc_out, ... );
345 \&
346 \& } OSSL_TRACE_END(TLS);
347 .Ve
348 .Sp
349 When the tracing API isn't operational, that will expand to:
350 .Sp
351 .Vb 10
352 \& do {
353 \& BIO *trc_out = NULL;
354 \& if (0) {
355 \& if (condition) {
356 \& ((void)0);
357 \& goto err;
358 \& }
359 \& BIO_printf(trc_out, ... );
360 \& }
361 \& } while (0);
362 .Ve
363 .SH "RETURN VALUES"
364 .IX Header "RETURN VALUES"
365 \&\fBOSSL_trace_enabled()\fR returns 1 if tracing for the given \fItype\fR is
366 operational and enabled, otherwise 0.
367 .PP
368 \&\fBOSSL_trace_begin()\fR returns a \fBBIO\fR pointer if the given \fItype\fR is enabled,
369 otherwise NULL.
370 .PP
371 \&\fBOSSL_trace_string()\fR returns the number of characters emitted, or \-1 on error.
372 .SH "SEE ALSO"
373 .IX Header "SEE ALSO"
374 \&\fBOSSL_trace_set_channel\fR\|(3), \fBOSSL_trace_set_callback\fR\|(3)
375 .SH HISTORY
376 .IX Header "HISTORY"
377 The OpenSSL Tracing functions were added in OpenSSL 3.0.
378 .PP
379 \&\fBOSSL_TRACE_STRING()\fR, OSSL_TRACE_STRING_MAX, and OSSL_trace_string
380 were added in OpenSSL 3.2.
381 .SH COPYRIGHT
382 .IX Header "COPYRIGHT"
383 Copyright 2019\-2025 The OpenSSL Project Authors. All Rights Reserved.
384 .PP
385 Licensed under the Apache License 2.0 (the "License"). You may not use
386 this file except in compliance with the License. You can obtain a copy
387 in the file LICENSE in the source distribution or at
388 <https://www.openssl.org/source/license.html>.