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