diff options
Diffstat (limited to 'secure/lib/libcrypto/man/man3/OSSL_trace_enabled.3')
| -rw-r--r-- | secure/lib/libcrypto/man/man3/OSSL_trace_enabled.3 | 220 |
1 files changed, 91 insertions, 129 deletions
diff --git a/secure/lib/libcrypto/man/man3/OSSL_trace_enabled.3 b/secure/lib/libcrypto/man/man3/OSSL_trace_enabled.3 index fe5f8c20303e..9ba476453e43 100644 --- a/secure/lib/libcrypto/man/man3/OSSL_trace_enabled.3 +++ b/secure/lib/libcrypto/man/man3/OSSL_trace_enabled.3 @@ -1,4 +1,5 @@ -.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45) .\" .\" Standard preamble: .\" ======================================================================== @@ -15,29 +16,12 @@ .ft R .fi .. -.\" Set up some character translations and predefined strings. \*(-- will -.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left -.\" double quote, and \*(R" will give a right double quote. \*(C+ will -.\" give a nicer C++. Capital omega is used to do unbreakable dashes and -.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, -.\" nothing in troff, for use with C<>. -.tr \(*W- -.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. .ie n \{\ -. ds -- \(*W- -. ds PI pi -. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch -. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch -. ds L" "" -. ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ -. ds -- \|\(em\| -. ds PI \(*p -. ds L" `` -. ds R" '' . ds C` . ds C' 'br\} @@ -68,83 +52,24 @@ . \} .\} .rr rF -.\" Fear. Run. Save yourself. No user-serviceable parts. -. \" fudge factors for nroff and troff -.if n \{\ -. ds #H 0 -. ds #V .8m -. ds #F .3m -. ds #[ \f1 -. ds #] \fP -.\} -.if t \{\ -. ds #H ((1u-(\\\\n(.fu%2u))*.13m) -. ds #V .6m -. ds #F 0 -. ds #[ \& -. ds #] \& -.\} -. \" simple accents for nroff and troff -.if n \{\ -. ds ' \& -. ds ` \& -. ds ^ \& -. ds , \& -. ds ~ ~ -. ds / -.\} -.if t \{\ -. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" -. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' -. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' -. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' -. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' -. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' -.\} -. \" troff and (daisy-wheel) nroff accents -.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' -.ds 8 \h'\*(#H'\(*b\h'-\*(#H' -.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] -.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' -.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' -.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] -.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] -.ds ae a\h'-(\w'a'u*4/10)'e -.ds Ae A\h'-(\w'A'u*4/10)'E -. \" corrections for vroff -.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' -.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' -. \" for low resolution devices (crt and lpr) -.if \n(.H>23 .if \n(.V>19 \ -\{\ -. ds : e -. ds 8 ss -. ds o a -. ds d- d\h'-1'\(ga -. ds D- D\h'-1'\(hy -. ds th \o'bp' -. ds Th \o'LP' -. ds ae ae -. ds Ae AE -.\} -.rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "OSSL_TRACE_ENABLED 3ossl" -.TH OSSL_TRACE_ENABLED 3ossl "2023-09-19" "3.0.11" "OpenSSL" +.TH OSSL_TRACE_ENABLED 3ossl 2025-07-01 3.5.1 OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh -.SH "NAME" +.SH NAME OSSL_trace_enabled, OSSL_trace_begin, OSSL_trace_end, OSSL_TRACE_BEGIN, OSSL_TRACE_END, OSSL_TRACE_CANCEL, OSSL_TRACE, OSSL_TRACE1, OSSL_TRACE2, OSSL_TRACE3, OSSL_TRACE4, OSSL_TRACE5, OSSL_TRACE6, OSSL_TRACE7, OSSL_TRACE8, OSSL_TRACE9, OSSL_TRACEV, +OSSL_TRACE_STRING, OSSL_TRACE_STRING_MAX, OSSL_trace_string, OSSL_TRACE_ENABLED \&\- OpenSSL Tracing API -.SH "SYNOPSIS" +.SH SYNOPSIS .IX Header "SYNOPSIS" .Vb 1 \& #include <openssl/trace.h> @@ -166,62 +91,71 @@ OSSL_TRACE_ENABLED \& } OSSL_TRACE_END(category); \& \& /* one\-shot trace macros */ +\& OSSL_TRACE(category, text) \& OSSL_TRACE1(category, format, arg1) \& OSSL_TRACE2(category, format, arg1, arg2) \& ... \& OSSL_TRACE9(category, format, arg1, ..., arg9) +\& OSSL_TRACE_STRING(category, text, full, data, len) +\& +\& #define OSSL_TRACE_STRING_MAX 80 +\& int OSSL_trace_string(BIO *out, int text, int full, +\& const unsigned char *data, size_t size); \& \& /* check whether a trace category is enabled */ \& if (OSSL_TRACE_ENABLED(category)) { \& ... \& } .Ve -.SH "DESCRIPTION" +.SH DESCRIPTION .IX Header "DESCRIPTION" The functions described here are mainly interesting for those who provide OpenSSL functionality, either in OpenSSL itself or in engine modules or similar. .PP -If tracing is enabled (see \*(L"\s-1NOTES\*(R"\s0 below), these functions are used to -generate free text tracing output. +If the tracing facility is enabled (see "Configure Tracing" below), +these functions are used to generate free text tracing output. .PP The tracing output is divided into types which are enabled individually by the application. The tracing types are described in detail in -\&\*(L"Trace types\*(R" in \fBOSSL_trace_set_callback\fR\|(3). -The fallback type \fB\s-1OSSL_TRACE_CATEGORY_ALL\s0\fR should \fInot\fR be used +"Trace types" in \fBOSSL_trace_set_callback\fR\|(3). +The fallback type \fBOSSL_TRACE_CATEGORY_ALL\fR should \fInot\fR be used with the functions described here. .PP -Tracing for a specific category is enabled if a so called +Tracing for a specific category is enabled at run-time if a so-called \&\fItrace channel\fR is attached to it. A trace channel is simply a -\&\s-1BIO\s0 object to which the application can write its trace output. +BIO object to which the application can write its trace output. .PP The application has two different ways of registering a trace channel, -either by directly providing a \s-1BIO\s0 object using \fBOSSL_trace_set_channel()\fR, -or by providing a callback routine using \fBOSSL_trace_set_callback()\fR. -The latter is wrapped internally by a dedicated \s-1BIO\s0 object, so for the +either by directly providing a BIO object using \fBOSSL_trace_set_channel\fR\|(3), +or by providing a callback routine using \fBOSSL_trace_set_callback\fR\|(3). +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 \fIsimple trace channel\fR and a \fIcallback trace channel\fR, respectively. .PP To produce trace output, it is necessary to obtain a pointer to the -trace channel (i.e., the \s-1BIO\s0 object) using \fBOSSL_trace_begin()\fR, write -to it using arbitrary \s-1BIO\s0 output routines, and finally releases the +trace channel (i.e., the BIO object) using \fBOSSL_trace_begin()\fR, write +to it using arbitrary BIO output routines, and finally releases the channel using \fBOSSL_trace_end()\fR. The \fBOSSL_trace_begin()\fR/\fBOSSL_trace_end()\fR 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. .PP The tracing code normally does not call OSSL_trace_{begin,end}() directly, -but rather uses a set of convenience macros, see the \*(L"Macros\*(R" section below. -.SS "Functions" +but rather uses a set of convenience macros, see the "Macros" section below. +.SS Functions .IX Subsection "Functions" \&\fBOSSL_trace_enabled()\fR can be used to check if tracing for the given -\&\fIcategory\fR is enabled. +\&\fIcategory\fR is enabled, i.e., if the tracing facility has been statically +enabled (see "Configure Tracing" below) and a trace channel has been +registered using \fBOSSL_trace_set_channel\fR\|(3) or \fBOSSL_trace_set_callback\fR\|(3). .PP -\&\fBOSSL_trace_begin()\fR is used to starts a tracing section, and get the -channel for the given \fIcategory\fR in form of a \s-1BIO.\s0 -This \s-1BIO\s0 can only be used for output. +\&\fBOSSL_trace_begin()\fR is used to start a tracing section, +and get the channel for the given \fIcategory\fR in form of a BIO. +This BIO can only be used for output. +The pointer returned is NULL if the category is invalid or not enabled. .PP \&\fBOSSL_trace_end()\fR is used to end a tracing section. .PP @@ -229,18 +163,24 @@ Using \fBOSSL_trace_begin()\fR and \fBOSSL_trace_end()\fR to wrap tracing sectio is \fImandatory\fR. The result of trying to produce tracing output outside of such sections is undefined. -.SS "Macros" +.PP +\&\fBOSSL_trace_string()\fR outputs \fIdata\fR of length \fIsize\fR as a string on BIO \fIout\fR. +If \fItext\fR is 0, the function masks any included control characters apart from +newlines and makes sure for nonempty input that the output ends with a newline. +Unless \fIfull\fR is nonzero, the length is limited (with a suitable warning) +to \fBOSSL_TRACE_STRING_MAX\fR characters, which currently is 80. +.SS Macros .IX Subsection "Macros" There are a number of convenience macros defined, to make tracing easy and consistent. .PP -\&\s-1\fBOSSL_TRACE_BEGIN\s0()\fR and \s-1\fBOSSL_TRACE_END\s0()\fR reserve the \fB\s-1BIO\s0\fR \f(CW\*(C`trc_out\*(C'\fR and are +\&\fBOSSL_TRACE_BEGIN()\fR and \fBOSSL_TRACE_END()\fR reserve the \fBBIO\fR \f(CW\*(C`trc_out\*(C'\fR and are used as follows to wrap a trace section: .PP .Vb 1 \& OSSL_TRACE_BEGIN(TLS) { \& -\& BIO_fprintf(trc_out, ... ); +\& BIO_printf(trc_out, ... ); \& \& } OSSL_TRACE_END(TLS); .Ve @@ -252,13 +192,13 @@ This will normally expand to: \& BIO *trc_out = OSSL_trace_begin(OSSL_TRACE_CATEGORY_TLS); \& if (trc_out != NULL) { \& ... -\& BIO_fprintf(trc_out, ...); +\& BIO_printf(trc_out, ...); \& } \& OSSL_trace_end(OSSL_TRACE_CATEGORY_TLS, trc_out); \& } while (0); .Ve .PP -\&\s-1\fBOSSL_TRACE_CANCEL\s0()\fR must be used before returning from or jumping out of a +\&\fBOSSL_TRACE_CANCEL()\fR must be used before returning from or jumping out of a trace section: .PP .Vb 1 @@ -268,7 +208,7 @@ trace section: \& OSSL_TRACE_CANCEL(TLS); \& goto err; \& } -\& BIO_fprintf(trc_out, ... ); +\& BIO_printf(trc_out, ... ); \& \& } OSSL_TRACE_END(TLS); .Ve @@ -283,13 +223,13 @@ This will normally expand to: \& OSSL_trace_end(OSSL_TRACE_CATEGORY_TLS, trc_out); \& goto err; \& } -\& BIO_fprintf(trc_out, ... ); +\& BIO_printf(trc_out, ... ); \& } \& OSSL_trace_end(OSSL_TRACE_CATEGORY_TLS, trc_out); \& } while (0); .Ve .PP -\&\s-1\fBOSSL_TRACE\s0()\fR and \s-1\fBOSSL_TRACE1\s0()\fR, \s-1\fBOSSL_TRACE2\s0()\fR, ... \s-1\fBOSSL_TRACE9\s0()\fR are +\&\fBOSSL_TRACE()\fR and \fBOSSL_TRACE1()\fR, \fBOSSL_TRACE2()\fR, ... \fBOSSL_TRACE9()\fR are so-called one-shot macros: .PP The macro call \f(CW\*(C`OSSL_TRACE(category, text)\*(C'\fR, produces literal text trace output. @@ -300,18 +240,29 @@ It expands to: .PP .Vb 3 \& OSSL_TRACE_BEGIN(category) { -\& BIO_printf(trc_out, format, arg1, ..., argN) +\& BIO_printf(trc_out, format, arg1, ..., argN); \& } OSSL_TRACE_END(category) .Ve .PP -Internally, all one-shot macros are implemented using a generic \s-1\fBOSSL_TRACEV\s0()\fR +Internally, all one-shot macros are implemented using a generic \fBOSSL_TRACEV()\fR macro, since C90 does not support variadic macros. This helper macro has a rather weird synopsis and should not be used directly. .PP -The \s-1\fBOSSL_TRACE_ENABLED\s0()\fR macro can be used to conditionally execute some code +The macro call \f(CW\*(C`OSSL_TRACE_STRING(category, text, full, data, len)\*(C'\fR +outputs \fIdata\fR of length \fIsize\fR as a string +if tracing for the given \fIcategory\fR is enabled. +It expands to: +.PP +.Vb 3 +\& OSSL_TRACE_BEGIN(category) { +\& OSSL_trace_string(trc_out, text, full, data, len); +\& } OSSL_TRACE_END(category) +.Ve +.PP +The \fBOSSL_TRACE_ENABLED()\fR macro can be used to conditionally execute some code only if a specific trace category is enabled. In some situations this is simpler than entering a trace section using -\&\s-1\fBOSSL_TRACE_BEGIN\s0()\fR and \s-1\fBOSSL_TRACE_END\s0()\fR. +\&\fBOSSL_TRACE_BEGIN()\fR and \fBOSSL_TRACE_END()\fR. For example, the code .PP .Vb 3 @@ -327,8 +278,11 @@ expands to \& ... \& } .Ve -.SH "NOTES" +.SH NOTES .IX Header "NOTES" +It is not needed to guard trace output function calls like +\&\fIOSSL_TRACE(category, ...)\fR by \fIOSSL_TRACE_ENABLED(category)\fR. +.PP If producing the trace output requires carrying out auxiliary calculations, this auxiliary code should be placed inside a conditional block which is executed only if the trace category is enabled. @@ -370,15 +324,15 @@ use the tracing functionality documented here, it is therefore necessary to configure and build OpenSSL with the 'enable\-trace' option. .PP When the library is built with tracing disabled: -.IP "\(bu" 4 -The macro \fB\s-1OPENSSL_NO_TRACE\s0\fR is defined in \fI<openssl/opensslconf.h>\fR. -.IP "\(bu" 4 +.IP \(bu 4 +The macro \fBOPENSSL_NO_TRACE\fR is defined in \fI<openssl/opensslconf.h>\fR. +.IP \(bu 4 all functions are still present, but \fBOSSL_trace_enabled()\fR will always report the categories as disabled, and all other functions will do nothing. -.IP "\(bu" 4 +.IP \(bu 4 the convenience macros are defined to produce dead code. -For example, take this example from \*(L"Macros\*(R" section above: +For example, take this example from "Macros" section above: .Sp .Vb 1 \& OSSL_TRACE_BEGIN(TLS) { @@ -387,12 +341,12 @@ For example, take this example from \*(L"Macros\*(R" section above: \& OSSL_TRACE_CANCEL(TLS); \& goto err; \& } -\& BIO_fprintf(trc_out, ... ); +\& BIO_printf(trc_out, ... ); \& \& } OSSL_TRACE_END(TLS); .Ve .Sp -When the tracing \s-1API\s0 isn't operational, that will expand to: +When the tracing API isn't operational, that will expand to: .Sp .Vb 10 \& do { @@ -402,7 +356,7 @@ When the tracing \s-1API\s0 isn't operational, that will expand to: \& ((void)0); \& goto err; \& } -\& BIO_fprintf(trc_out, ... ); +\& BIO_printf(trc_out, ... ); \& } \& } while (0); .Ve @@ -411,16 +365,24 @@ When the tracing \s-1API\s0 isn't operational, that will expand to: \&\fBOSSL_trace_enabled()\fR returns 1 if tracing for the given \fItype\fR is operational and enabled, otherwise 0. .PP -\&\fBOSSL_trace_begin()\fR returns a \fB\s-1BIO\s0\fR pointer if the given \fItype\fR is enabled, -otherwise \s-1NULL.\s0 -.SH "HISTORY" +\&\fBOSSL_trace_begin()\fR returns a \fBBIO\fR pointer if the given \fItype\fR is enabled, +otherwise NULL. +.PP +\&\fBOSSL_trace_string()\fR returns the number of characters emitted, or \-1 on error. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBOSSL_trace_set_channel\fR\|(3), \fBOSSL_trace_set_callback\fR\|(3) +.SH HISTORY .IX Header "HISTORY" -The OpenSSL Tracing \s-1API\s0 was added in OpenSSL 3.0. -.SH "COPYRIGHT" +The OpenSSL Tracing API was added in OpenSSL 3.0. +.PP +\&\fBOSSL_TRACE_STRING()\fR, OSSL_TRACE_STRING_MAX, and OSSL_trace_string +were added in OpenSSL 3.2. +.SH COPYRIGHT .IX Header "COPYRIGHT" -Copyright 2019\-2021 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2019\-2023 The OpenSSL Project Authors. All Rights Reserved. .PP -Licensed under the Apache License 2.0 (the \*(L"License\*(R"). You may not use +Licensed under the Apache License 2.0 (the "License"). You may not use this file except in compliance with the License. You can obtain a copy -in the file \s-1LICENSE\s0 in the source distribution or at +in the file LICENSE in the source distribution or at <https://www.openssl.org/source/license.html>. |