mirror of
https://github.com/openssl/openssl.git
synced 2025-04-06 20:20:50 +08:00
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)
This commit is contained in:
Richard Levitte
parent
e19c5a1064
commit
2b93900e28
@ -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 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
|
||||
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.
|
||||
|
||||
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);
|
||||
|
||||
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.
|
||||
There are two exceptions:
|
||||
|
||||
The trailing section of a reason code (after the "_R_") is translated
|
||||
into lowercase and underscores changed to spaces.
|
||||
=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
|
||||
|
||||
[These are OpenSSL specific recommendations]
|
||||
|
||||
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
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user