Browse Source

trace: update the documentation

This commit adds some missing symbols and other minor enhancements.
In particular, it establishes the term 'channel' as a synonym for
a BIO object attached to a trace category, and introduces the
concept of a 'simple' channel versus a 'callback' channel.

Reviewed-by: Paul Dale <paul.dale@oracle.com>
Reviewed-by: Richard Levitte <levitte@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/8463)
master
Dr. Matthias St. Pierre 3 years ago
parent
commit
c37e635065
3 changed files with 78 additions and 13 deletions
  1. +51
    -4
      doc/man3/OSSL_trace_enabled.pod
  2. +21
    -9
      doc/man3/OSSL_trace_set_channel.pod
  3. +6
    -0
      util/private.num

+ 51
- 4
doc/man3/OSSL_trace_enabled.pod View File

@ -2,7 +2,8 @@
=head1 NAME
OSSL_trace_enabled, OSSL_trace_begin, OSSL_trace_end
OSSL_trace_enabled, OSSL_trace_begin, OSSL_trace_end,
OSSL_TRACE_BEGIN, OSSL_TRACE_END, OSSL_TRACE1, OSSL_TRACE2, OSSL_TRACE9
- OpenSSL Tracing API
=head1 SYNOPSIS
@ -14,6 +15,18 @@ OSSL_trace_enabled, OSSL_trace_begin, OSSL_trace_end
BIO *OSSL_trace_begin(int category);
void OSSL_trace_end(int category, BIO *channel);
/* trace group macros */
OSSL_TRACE_BEGIN(category) {
...
} OSSL_TRACE_END(category);
/* one-shot trace macros */
OSSL_TRACE1(category, format, arg1)
OSSL_TRACE2(category, format, arg1, arg2)
...
OSSL_TRACE9(category, format, arg1, ..., arg9)
=head1 DESCRIPTION
The functions described here are mainly interesting for those who provide
@ -30,6 +43,30 @@ L<OSSL_trace_set_callback(3)/Trace types>.
The fallback type C<OSSL_TRACE_CATEGORY_ANY> should I<not> be used
with the functions described here.
Tracing for a specific category is enabled if a so called
I<trace channel> is attached to it. A trace channel is simply a
BIO object to which the application can write its trace output.
The application has two different ways of registering a trace channel,
either by directly providing a BIO object using OSSL_trace_set_channel(),
or by providing a callback routine using OSSL_trace_set_callback().
The latter is wrapped internally by a dedicated BIO object, so for the
tracing code both channel types are effectively indistinguishable.
We call them a I<simple trace channel> and a I<callback trace channel>,
respectively.
To produce trace output, it is necessary to obtain a pointer to the
trace channel (i.e., the BIO object) using OSSL_trace_begin(), write
to it using arbitrary BIO output routines, and finally releases the
channel using OSSL_trace_end(). The OSSL_trace_begin()/OSSL_trace_end()
calls surrounding the trace output create a group, which acts as a
critical section (guarded by a mutex) to ensure that the trace output
of different threads does not get mixed up.
The tracing code normally does not call OSSL_trace_{begin,end}() directly,
but rather uses a set of convenience macros, see the L</Macros> section below.
=head2 Functions
OSSL_trace_enabled() can be used to check if tracing for the given
@ -46,7 +83,7 @@ is I<mandatory>.
The result of trying to produce tracing output outside of such
sections is undefined.
=head2 Convenience Macros
=head2 Macros
There are a number of convenience macros defined, to make tracing
easy and consistent.
@ -60,7 +97,7 @@ the B<BIO> C<trc_out> and are used as follows to wrap a trace section:
} OSSL_TRACE_END(TLS);
This will normally expands to:
This will normally expand to:
do {
BIO *trc_out = OSSL_trace_begin(OSSL_TRACE_CATEGORY_TLS);
@ -98,6 +135,16 @@ This will normally expand to:
OSSL_trace_end(OSSL_TRACE_CATEGORY_TLS, trc_out);
} while (0);
C<OSSL_TRACE1()>, ... C<OSSL_TRACE9()> are one-shot macros which essentially wrap
a single BIO_printf() into a tracing group.
The call OSSL_TRACEn(category, format, arg1, ..., argN) expands to:
OSSL_TRACE_BEGIN(category) {
BIO_printf(trc_out, format, arg1, ..., argN)
} OSSL_TRACE_END(category)
=head1 NOTES
It is advisable to always check that a trace type is enabled with
@ -133,7 +180,7 @@ nothing.
=item *
the convenience macros are defined to produce dead code.
For example, take this example from L</Convenience Macros> above:
For example, take this example from L</Macros> section above:
OSSL_TRACE_BEGIN(TLS) {


+ 21
- 9
doc/man3/OSSL_trace_set_channel.pod View File

@ -25,14 +25,21 @@ This output comes in form of free text for humans to read.
The trace output is divided into categories which can be
enabled individually.
They are enabled by giving them a channel in form of a BIO, or a
tracer callback, which is responsible for performing the actual
output.
Every category can be enabled individually by attaching a so called
I<trace channel> to it, which in the simplest case is just a BIO object
to which the application can write the tracing output for this category.
Alternatively, the application can provide a tracer callback in order to
get more finegrained trace information. This callback will be wrapped
internally by a dedicated BIO object.
For the tracing code, both trace channel types are indistinguishable.
These are called a I<simple trace channel> and a I<callback trace channel>,
respectively.
=head2 Functions
OSSL_trace_set_channel() is used to enable the given trace C<category>
by giving it the B<BIO> C<bio>.
by attaching the B<BIO> C<bio> object as (simple) trace channel.
OSSL_trace_set_prefix() and OSSL_trace_set_suffix() can be used to add
an extra line for each channel, to be output before and after group of
@ -46,7 +53,8 @@ OSSL_trace_set_callback() instead.
OSSL_trace_set_callback() is used to enable the given trace
C<category> by giving it the tracer callback C<cb> with the associated
data C<data>, which will simply be passed through to C<cb> whenever
it's called.
it's called. The callback function is internally wrapped by a
dedicated BIO object, the so called I<callback trace channel>.
This should be used when it's desirable to do form the trace output to
something suitable for application needs where a prefix and suffix
line aren't enough.
@ -78,9 +86,13 @@ callback the possibility to output a dynamic starting line, or set a
prefix that should be output at the beginning of each line, or
something other.
=item C<OSSL_TRACE_CTRL_DURING>
=item C<OSSL_TRACE_CTRL_WRITE>
The callback is called from any regular BIO output routine.
This callback is called whenever data is written to the BIO by some
regular BIO output routine.
An arbitrary number of C<OSSL_TRACE_CTRL_WRITE> callbacks can occur
inside a group marked by a pair of C<OSSL_TRACE_CTRL_BEGIN> and
C<OSSL_TRACE_CTRL_END> calls, but never outside such a group.
=item C<OSSL_TRACE_CTRL_END>
@ -177,8 +189,8 @@ success, or 0 on failure.
=head1 EXAMPLES
In all examples below, we assume that the trace producing code is
this:
In all examples below, the trace producing code is assumed to be
the following:
int foo = 42;
const char bar[] = { 0, 1, 2, 3, 4, 5, 6, 7,


+ 6
- 0
util/private.num View File

@ -503,3 +503,9 @@ ASYNC_STATUS_EAGAIN define
ASYNC_STATUS_OK define
ASYNC_STATUS_ERR define
ASYNC_STATUS_UNSUPPORTED define
OSSL_TRACE_BEGIN define
OSSL_TRACE_END define
OSSL_TRACE_CANCEL define
OSSL_TRACE1 define
OSSL_TRACE2 define
OSSL_TRACE9 define

Loading…
Cancel
Save