DOC: Rewrite the section on reporting errors in doc/man3/ERR_put_error.pod

Reviewed-by: Paul Dale <paul.dale@oracle.com>
(Merged from https://github.com/openssl/openssl/pull/13320)

1 files 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<ERR_LIB_XXX> and has its own set
+of reason codes B<XXX_R_...>.  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<XXX_F_...>, the second
-argument is a reason code B<XXX_R_...>. 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<ERR_LIB_SYS>
+
+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<must>
+be L<errno(3)>.
+
+ ERR_raise(ERR_LIB_SYS, errno);
+
+=item B<ERR_R_XXX>
+
+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<ERR_get_next_error_library(3)>; 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</OpenSSL library reports> above are valid for
+other pieces of software, i.e. they may use B<ERR_LIB_SYS> to report system
+errors:
+
+ ERR_raise(ERR_LIB_SYS, errno);
+
+... and they may use B<ERR_R_XXX> 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<ERR_LIB_XXX> 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<ERR_LIB_ASN1>
+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<ERR_load_strings(3)>
+L<ERR_load_strings(3)>, L<ERR_get_next_error_library(3)>
 
 =head1 HISTORY
 
-B<ERR_add_error_txt> and B<ERR_add_error_mem_bio> 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