From 2b93900e28b330e6066a993278fabd4d560936f9 Mon Sep 17 00:00:00 2001 From: Richard Levitte Date: Sat, 14 Nov 2020 11:58:17 +0100 Subject: DOC: Rewrite the section on reporting errors in doc/man3/ERR_put_error.pod Reviewed-by: Paul Dale (Merged from https://github.com/openssl/openssl/pull/13320) --- doc/man3/ERR_put_error.pod | 105 ++++++++++++++++++++++++++++++++++++--------- 1 file changed, 85 insertions(+), 20 deletions(-) diff --git a/doc/man3/ERR_put_error.pod b/doc/man3/ERR_put_error.pod index c6b42028cc..a4e0cd6bec 100644 --- a/doc/man3/ERR_put_error.pod +++ b/doc/man3/ERR_put_error.pod @@ -1,5 +1,7 @@ =pod +=for openssl foreign manual errno(3) + =head1 NAME ERR_raise, ERR_raise_data, @@ -65,50 +67,113 @@ error messages for the error code. =head2 Reporting errors -=for comment TODO(3.0) should this be internal documentation? +=head3 OpenSSL library reports + +Each OpenSSL sub-library has library code B and has its own set +of reason codes B. These are both passed in combination to +ERR_raise() and ERR_raise_data(), and the combination ultimately produces +the correct error text for the reported error. -Each sub-library has a specific macro XXXerr() that is used to report -errors. Its first argument is a function code B, the second -argument is a reason code B. Function codes are derived -from the function names; reason codes consist of textual error +All these macros and the numbers they have as values are specific to +OpenSSL's libraries. OpenSSL reason codes normally consist of textual error descriptions. For example, the function ssl3_read_bytes() reports a "handshake failure" as follows: - SSLerr(SSL_F_SSL3_READ_BYTES, SSL_R_SSL_HANDSHAKE_FAILURE); + ERR_raise(ERR_LIB_SSL, SSL_R_SSL_HANDSHAKE_FAILURE); + +There are two exceptions: + +=over 4 + +=item B + +This "library code" indicates that a system error is being reported. In +this case, the reason code given to ERR_raise() and ERR_raise_data() I +be L. + + ERR_raise(ERR_LIB_SYS, errno); + +=item B + +This set of error codes is considered global, and may be used in combination +with any sub-library code. + + ERR_raise(ERR_LIB_RSA, ERR_R_PASSED_INVALID_ARGUMENT); + +=back + +=head3 Other pieces of software + +Other pieces of software that may want to use OpenSSL's error reporting +system, such as engines or applications, must normally get their own +numbers. + +=over 4 + +=item * + +To get a "library" code, call L; this gives +the calling code a dynamic number, usable for the duration of the process. + +=item * + +Reason codes for each such "library" are determined or generated by the +authors of that code. They must be numbers in the range 1 to 524287 (in +other words, they must be nonzero unsigned 18 bit integers). + +=back + +The exceptions mentioned in L above are valid for +other pieces of software, i.e. they may use B to report system +errors: + + ERR_raise(ERR_LIB_SYS, errno); + +... and they may use B macros together with their own "library" +code. + + int app_lib_code = ERR_get_next_error_library(); + + /* ... */ + + ERR_raise(app_lib_code, ERR_R_PASSED_INVALID_ARGUMENT); + +=begin comment -Function and reason codes should consist of uppercase characters, -numbers and underscores only. The error file generation script translates -function codes into function names by looking in the header files -for an appropriate function name, if none is found it just uses -the capitalized form such as "SSL3_READ_BYTES" in the above example. +[These are OpenSSL specific recommendations] -The trailing section of a reason code (after the "_R_") is translated -into lowercase and underscores changed to spaces. +Reason codes should consist of uppercase characters, numbers and underscores +only. The error file generation script translates the trailing section of a +reason code (after the "_R_") into lowercase with underscores changed to +spaces. Although a library will normally report errors using its own specific -XXXerr macro, another library's macro can be used. This is normally -only done when a library wants to include ASN1 code which must use -the ASN1err() macro. +B macro, another library's macro can be used, together with +that other library's reason codes. This is normally only done when a library +wants to include ASN1 code which must be combined with B +macro. +=end comment =head1 RETURN VALUES -ERR_raise(), ERR_put_error(), +ERR_raise(), ERR_raise_data(), ERR_put_error(), ERR_add_error_data(), ERR_add_error_vdata() ERR_add_error_txt(), and ERR_add_error_mem_bio() return no values. =head1 NOTES -ERR_raise() and ERR_put_error() are implemented as macros. +ERR_raise(), ERR_raise() and ERR_put_error() are implemented as macros. =head1 SEE ALSO -L +L, L =head1 HISTORY -B and B were added in OpenSSL 3.0. +ERR_raise, ERR_raise_data, ERR_add_error_txt() and ERR_add_error_mem_bio() +were added in OpenSSL 3.0. =head1 COPYRIGHT -- cgit v1.2.3