|
@@ -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
|
|
|
|