ecb88ab0ab695848f3b38a6906d51943b716770b
[openssl.git] / doc / man3 / OSSL_trace_enabled.pod
1 =pod
2
3 =head1 NAME
4
5 OSSL_trace_enabled, OSSL_trace_begin, OSSL_trace_end
6 - OpenSSL Tracing API
7
8 =head1 SYNOPSIS
9
10  #include <openssl/trace.h>
11
12  int OSSL_trace_enabled(int category);
13
14  BIO *OSSL_trace_begin(int category);
15  void OSSL_trace_end(int category, BIO *channel);
16
17 =head1 DESCRIPTION
18
19 The functions described here are mainly interesting for those who provide
20 OpenSSL functionality, either in OpenSSL itself or in engine modules
21 or similar.
22
23 If operational (see L</NOTES> below), these functions are used to
24 generate free text tracing output.
25
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.
32
33 =head2 Functions
34
35 OSSL_trace_enabled() can be used to check if tracing for the given
36 C<category> is enabled.
37
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.
41
42 OSSL_trace_end() is used to end a tracing section.
43
44 Using OSSL_trace_begin() and OSSL_trace_end() to wrap tracing sections
45 is I<mandatory>.
46 The result of trying to produce tracing output outside of such
47 sections is undefined.
48
49 =head2 Convenience Macros
50
51 There are a number of convenience macros defined, to make tracing
52 easy and consistent.
53
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:
56
57  OSSL_TRACE_BEGIN(TLS) {
58
59      BIO_fprintf(trc_out, ... );
60
61  } OSSL_TRACE_END(TLS);
62
63 This will normally expands to:
64
65  do {
66      BIO *trc_out = OSSL_trace_begin(OSSL_TRACE_CATEGORY_TLS);
67      if (trc_out != NULL) {
68          ...
69          BIO_fprintf(trc_out, ...);
70      }
71      OSSL_trace_end(OSSL_TRACE_CATEGORY_TLS, trc_out);
72  } while (0);
73
74 C<OSSL_TRACE_CANCEL(category)> must be used before returning from or
75 jumping out of a trace section:
76
77  OSSL_TRACE_BEGIN(TLS) {
78
79      if (condition) {
80          OSSL_TRACE_CANCEL(TLS);
81          goto err;
82      }
83      BIO_fprintf(trc_out, ... );
84
85  } OSSL_TRACE_END(TLS);
86
87 This will normally expand to:
88
89  do {
90      BIO *trc_out = OSSL_trace_begin(OSSL_TRACE_CATEGORY_TLS);
91      if (trc_out != NULL) {
92          if (condition) {
93              OSSL_trace_end(OSSL_TRACE_CATEGORY_TLS, trc_out);
94              goto err;
95          }
96          BIO_fprintf(trc_out, ... );
97      }
98      OSSL_trace_end(OSSL_TRACE_CATEGORY_TLS, trc_out);
99  } while (0);
100
101 =head1 NOTES
102
103 It is advisable to always check that a trace type is enabled with
104 OSSL_trace_enabled() before generating any output, for example:
105
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);
111     }
112
113 =head2 Tracing disabled
114
115 The OpenSSL library may be built with tracing disabled, which makes
116 everything documented here inoperational.
117
118 When the library is built with tracing disabled:
119
120 =over 4
121
122 =item *
123
124 The macro C<OPENSSL_NO_TRACE> is defined in C<openssl/opensslconf.h>.
125
126 =item *
127
128 all functions are still present, bu OSSL_trace_enabled() will always
129 report the categories as disabled, and all other functions will do
130 nothing.
131
132 =item *
133
134 the convenience macros are defined to produce dead code.
135 For example, take this example from L</Convenience Macros> above:
136
137  OSSL_TRACE_BEGIN(TLS) {
138
139      if (condition) {
140          OSSL_TRACE_CANCEL(TLS);
141          goto err;
142      }
143      BIO_fprintf(trc_out, ... );
144
145  } OSSL_TRACE_END(TLS);
146
147 When the tracing API isn't operational, that will expand to:
148
149  do {
150      BIO *trc_out = NULL;
151      if (0) {
152          if (condition) {
153              ((void)0);
154              goto err;
155          }
156          BIO_fprintf(trc_out, ... );
157      }
158  } while (0);
159
160 =back
161
162 =head1 RETURN VALUES
163
164 OSSL_trace_enabled() returns 1 if tracing for the given B<type> is
165 operational and enabled, otherwise 0.
166
167 OSSL_trace_begin() returns a C<BIO *> if the given B<type> is enabled,
168 otherwise C<NULL>.
169
170 =head1 HISTORY
171
172 The OpenSSL Tracing API was added ino OpenSSL 3.0.0.
173
174 =head1 COPYRIGHT
175
176 Copyright 2019 The OpenSSL Project Authors. All Rights Reserved.
177
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>.
182
183 =cut