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 operational (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 Tracing disabled
115 The OpenSSL library may be built with tracing disabled, which makes
116 everything documented here inoperational.
118 When the library is built with tracing disabled:
124 The macro C<OPENSSL_NO_TRACE> is defined in C<openssl/opensslconf.h>.
128 all functions are still present, bu OSSL_trace_enabled() will always
129 report the categories as disabled, and all other functions will do
134 the convenience macros are defined to produce dead code.
135 For example, take this example from L</Convenience Macros> above:
137 OSSL_TRACE_BEGIN(TLS) {
140 OSSL_TRACE_CANCEL(TLS);
143 BIO_fprintf(trc_out, ... );
145 } OSSL_TRACE_END(TLS);
147 When the tracing API isn't operational, that will expand to:
156 BIO_fprintf(trc_out, ... );
164 OSSL_trace_enabled() returns 1 if tracing for the given B<type> is
165 operational and enabled, otherwise 0.
167 OSSL_trace_begin() returns a C<BIO *> if the given B<type> is enabled,
172 The OpenSSL Tracing API was added ino OpenSSL 3.0.0.
176 Copyright 2019 The OpenSSL Project Authors. All Rights Reserved.
178 Licensed under the Apache License 2.0 (the "License"). You may not use
179 this file except in compliance with the License. You can obtain a copy
180 in the file LICENSE in the source distribution or at
181 L<https://www.openssl.org/source/license.html>.