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