doc/man3/OSSL_trace_enabled.pod

   1 =pod
   2
   3 =head1 NAME
   4
   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,
   9 OSSL_TRACEV,
  10 OSSL_TRACE_ENABLED
  11 - OpenSSL Tracing API
  12
  13 =head1 SYNOPSIS
  14
  15 =for openssl generic
  16
  17  #include <openssl/trace.h>
  18
  19  int OSSL_trace_enabled(int category);
  20
  21  BIO *OSSL_trace_begin(int category);
  22  void OSSL_trace_end(int category, BIO *channel);
  23
  24  /* trace group macros */
  25  OSSL_TRACE_BEGIN(category) {
  26      ...
  27      if (some_error) {
  28          /* Leave trace group prematurely in case of an error */
  29          OSSL_TRACE_CANCEL(category);
  30          goto err;
  31      }
  32      ...
  33  } OSSL_TRACE_END(category);
  34
  35  /* one-shot trace macros */
  36  OSSL_TRACE(category, text)
  37  OSSL_TRACE1(category, format, arg1)
  38  OSSL_TRACE2(category, format, arg1, arg2)
  39  ...
  40  OSSL_TRACE9(category, format, arg1, ..., arg9)
  41
  42  /* check whether a trace category is enabled */
  43  if (OSSL_TRACE_ENABLED(category)) {
  44      ...
  45  }
  46
  47 =head1 DESCRIPTION
  48
  49 The functions described here are mainly interesting for those who provide
  50 OpenSSL functionality, either in OpenSSL itself or in engine modules
  51 or similar.
  52
  53 If the tracing facility is enabled (see L</Configure Tracing> below),
  54 these functions are used to generate free text tracing output.
  55
  56 The tracing output is divided into types which are enabled
  57 individually by the application.
  58 The tracing types are described in detail in
  59 L<OSSL_trace_set_callback(3)/Trace types>.
  60 The fallback type B<OSSL_TRACE_CATEGORY_ALL> should I<not> be used
  61 with the functions described here.
  62
  63 Tracing for a specific category is enabled at run-time if a so-called
  64 I<trace channel> is attached to it. A trace channel is simply a
  65 BIO object to which the application can write its trace output.
  66
  67 The application has two different ways of registering a trace channel,
  68 either by directly providing a BIO object using L<OSSL_trace_set_channel(3)>,
  69 or by providing a callback routine using L<OSSL_trace_set_callback(3)>.
  70 The latter is wrapped internally by a dedicated BIO object, so for the
  71 tracing code both channel types are effectively indistinguishable.
  72 We call them a I<simple trace channel> and a I<callback trace channel>,
  73 respectively.
  74
  75 To produce trace output, it is necessary to obtain a pointer to the
  76 trace channel (i.e., the BIO object) using OSSL_trace_begin(), write
  77 to it using arbitrary BIO output routines, and finally releases the
  78 channel using OSSL_trace_end(). The OSSL_trace_begin()/OSSL_trace_end()
  79 calls surrounding the trace output create a group, which acts as a
  80 critical section (guarded by a mutex) to ensure that the trace output
  81 of different threads does not get mixed up.
  82
  83 The tracing code normally does not call OSSL_trace_{begin,end}() directly,
  84 but rather uses a set of convenience macros, see the L</Macros> section below.
  85
  86
  87 =head2 Functions
  88
  89 OSSL_trace_enabled() can be used to check if tracing for the given
  90 I<category> is enabled, i.e., if the tracing facility has been statically
  91 enabled (see L</Configure Tracing> below) and a trace channel has been
  92 registered using L<OSSL_trace_set_channel(3)> or L<OSSL_trace_set_callback(3)>.
  93
  94 OSSL_trace_begin() is used to starts a tracing section, and get the
  95 channel for the given I<category> in form of a BIO.
  96 This BIO can only be used for output.
  97
  98 OSSL_trace_end() is used to end a tracing section.
  99
 100 Using OSSL_trace_begin() and OSSL_trace_end() to wrap tracing sections
 101 is I<mandatory>.
 102 The result of trying to produce tracing output outside of such
 103 sections is undefined.
 104
 105 =head2 Macros
 106
 107 There are a number of convenience macros defined, to make tracing
 108 easy and consistent.
 109
 110 OSSL_TRACE_BEGIN() and OSSL_TRACE_END() reserve the B<BIO> C<trc_out> and are
 111 used as follows to wrap a trace section:
 112
 113  OSSL_TRACE_BEGIN(TLS) {
 114
 115      BIO_printf(trc_out, ... );
 116
 117  } OSSL_TRACE_END(TLS);
 118
 119 This will normally expand to:
 120
 121  do {
 122      BIO *trc_out = OSSL_trace_begin(OSSL_TRACE_CATEGORY_TLS);
 123      if (trc_out != NULL) {
 124          ...
 125          BIO_printf(trc_out, ...);
 126      }
 127      OSSL_trace_end(OSSL_TRACE_CATEGORY_TLS, trc_out);
 128  } while (0);
 129
 130 OSSL_TRACE_CANCEL() must be used before returning from or jumping out of a
 131 trace section:
 132
 133  OSSL_TRACE_BEGIN(TLS) {
 134
 135      if (some_error) {
 136          OSSL_TRACE_CANCEL(TLS);
 137          goto err;
 138      }
 139      BIO_printf(trc_out, ... );
 140
 141  } OSSL_TRACE_END(TLS);
 142
 143 This will normally expand to:
 144
 145  do {
 146      BIO *trc_out = OSSL_trace_begin(OSSL_TRACE_CATEGORY_TLS);
 147      if (trc_out != NULL) {
 148          if (some_error) {
 149              OSSL_trace_end(OSSL_TRACE_CATEGORY_TLS, trc_out);
 150              goto err;
 151          }
 152          BIO_printf(trc_out, ... );
 153      }
 154      OSSL_trace_end(OSSL_TRACE_CATEGORY_TLS, trc_out);
 155  } while (0);
 156
 157
 158 OSSL_TRACE() and OSSL_TRACE1(), OSSL_TRACE2(), ... OSSL_TRACE9() are
 159 so-called one-shot macros:
 160
 161 The macro call C<OSSL_TRACE(category, text)>, produces literal text trace output.
 162
 163 The macro call C<OSSL_TRACEn(category, format, arg1, ..., argn)> produces
 164 printf-style trace output with n format field arguments (n=1,...,9).
 165 It expands to:
 166
 167  OSSL_TRACE_BEGIN(category) {
 168      BIO_printf(trc_out, format, arg1, ..., argN)
 169  } OSSL_TRACE_END(category)
 170
 171 Internally, all one-shot macros are implemented using a generic OSSL_TRACEV()
 172 macro, since C90 does not support variadic macros. This helper macro has a rather
 173 weird synopsis and should not be used directly.
 174
 175 The OSSL_TRACE_ENABLED() macro can be used to conditionally execute some code
 176 only if a specific trace category is enabled.
 177 In some situations this is simpler than entering a trace section using
 178 OSSL_TRACE_BEGIN() and OSSL_TRACE_END().
 179 For example, the code
 180
 181  if (OSSL_TRACE_ENABLED(TLS)) {
 182      ...
 183  }
 184
 185 expands to
 186
 187  if (OSSL_trace_enabled(OSSL_TRACE_CATEGORY_TLS) {
 188      ...
 189  }
 190
 191 =head1 NOTES
 192
 193 If producing the trace output requires carrying out auxiliary calculations,
 194 this auxiliary code should be placed inside a conditional block which is
 195 executed only if the trace category is enabled.
 196
 197 The most natural way to do this is to place the code inside the trace section
 198 itself because it already introduces such a conditional block.
 199
 200  OSSL_TRACE_BEGIN(TLS) {
 201      int var = do_some_auxiliary_calculation();
 202
 203      BIO_printf(trc_out, "var = %d\n", var);
 204
 205  } OSSL_TRACE_END(TLS);
 206
 207 In some cases it is more advantageous to use a simple conditional group instead
 208 of a trace section. This is the case if calculations and tracing happen in
 209 different locations of the code, or if the calculations are so time consuming
 210 that placing them inside a (critical) trace section would create too much
 211 contention.
 212
 213  if (OSSL_TRACE_ENABLED(TLS)) {
 214      int var = do_some_auxiliary_calculation();
 215
 216      OSSL_TRACE1("var = %d\n", var);
 217  }
 218
 219 Note however that premature optimization of tracing code is in general futile
 220 and it's better to keep the tracing code as simple as possible.
 221 Because most often the limiting factor for the application's speed is the time
 222 it takes to print the trace output, not to calculate it.
 223
 224 =head2 Configure Tracing
 225
 226 By default, the OpenSSL library is built with tracing disabled. To
 227 use the tracing functionality documented here, it is therefore
 228 necessary to configure and build OpenSSL with the 'enable-trace' option.
 229
 230 When the library is built with tracing disabled:
 231
 232 =over 4
 233
 234 =item *
 235
 236 The macro B<OPENSSL_NO_TRACE> is defined in F<< <openssl/opensslconf.h> >>.
 237
 238 =item *
 239
 240 all functions are still present, but OSSL_trace_enabled() will always
 241 report the categories as disabled, and all other functions will do
 242 nothing.
 243
 244 =item *
 245
 246 the convenience macros are defined to produce dead code.
 247 For example, take this example from L</Macros> section above:
 248
 249  OSSL_TRACE_BEGIN(TLS) {
 250
 251      if (condition) {
 252          OSSL_TRACE_CANCEL(TLS);
 253          goto err;
 254      }
 255      BIO_printf(trc_out, ... );
 256
 257  } OSSL_TRACE_END(TLS);
 258
 259 When the tracing API isn't operational, that will expand to:
 260
 261  do {
 262      BIO *trc_out = NULL;
 263      if (0) {
 264          if (condition) {
 265              ((void)0);
 266              goto err;
 267          }
 268          BIO_printf(trc_out, ... );
 269      }
 270  } while (0);
 271
 272 =back
 273
 274 =head1 RETURN VALUES
 275
 276 OSSL_trace_enabled() returns 1 if tracing for the given I<type> is
 277 operational and enabled, otherwise 0.
 278
 279 OSSL_trace_begin() returns a B<BIO> pointer if the given I<type> is enabled,
 280 otherwise NULL.
 281
 282 =head1 SEE ALSO
 283
 284 L<OSSL_trace_set_channel(3)>, L<OSSL_trace_set_callback(3)>
 285
 286 =head1 HISTORY
 287
 288 The OpenSSL Tracing API was added in OpenSSL 3.0.
 289
 290 =head1 COPYRIGHT
 291
 292 Copyright 2019-2021 The OpenSSL Project Authors. All Rights Reserved.
 293
 294 Licensed under the Apache License 2.0 (the "License").  You may not use
 295 this file except in compliance with the License.  You can obtain a copy
 296 in the file LICENSE in the source distribution or at
 297 L<https://www.openssl.org/source/license.html>.
 298
 299 =cut