Extend -show_chain option to verify to show more info

[openssl.git] / doc / crypto / err.pod

diff --git a/doc/crypto/err.pod b/doc/crypto/err.pod
index e639dbd81eb7b216b8642cf7717a0094cc2eb95e..1a19a19a80f89623ed7dea2ba2d8426945d64d1d 100644 (file)
--- a/doc/crypto/err.pod
+++ b/doc/crypto/err.pod
@@ -2,7 +2,7 @@
 
 =head1 NAME
 
-err - Error codes
+err - error codes
 
 =head1 SYNOPSIS
 
@@ -46,7 +46,7 @@ err - Error codes
 
 =head1 DESCRIPTION
 
-When a call to the OpenSSL library fails, this is usually signalled
+When a call to the OpenSSL library fails, this is usually signaled
 by the return value, and an error code is stored in an error queue
 associated with the current thread. The B<err> library provides
 functions to obtain these error codes and textual error messages.
@@ -79,19 +79,28 @@ 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
-descriptions. For example, the function ssl23_read() reports a
+descriptions. For example, the function ssl3_read_bytes() reports a
 "handshake failure" as follows:
 
- SSLerr(SSL_F_SSL23_READ, SSL_R_SSL_HANDSHAKE_FAILURE);
+ SSLerr(SSL_F_SSL3_READ_BYTES, SSL_R_SSL_HANDSHAKE_FAILURE);
+
+Function and reason codes should consist of upper case 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.
+
+The trailing section of a reason code (after the "_R_") is translated
+into lower case and underscores changed to spaces.
 
 When you are using new function or reason codes, run B<make errors>.
 The necessary B<#define>s will then automatically be added to the
 sub-library's header file.
 
 Although a library will normally report errors using its own specific
-macro, a different macro is used. This is normally only done when a
-library wants to include ASN1 code which must user the ASN1 libraries
-error macro.
+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.
 
 =head2 Adding new libraries
 
@@ -134,7 +143,7 @@ The closing #endif etc will be automatically added by the script.
 
 The generated C error code file B<xxx_err.c> will load the header
 files B<stdio.h>, B<openssl/err.h> and B<openssl/xxx.h> so the
-header file must load any additional header files containg any
+header file must load any additional header files containing any
 definitions it uses.
 
 =head1 USING ERROR CODES IN EXTERNAL LIBRARIES
@@ -162,8 +171,7 @@ ERR_get_string_table(void) respectively.
 
 =head1 SEE ALSO
 
-L<CRYPTO_set_id_callback(3)|CRYPTO_set_id_callback(3)>,
-L<CRYPTO_set_locking_callback(3)|<CRYPTO_set_locking_callback(3)>,
+L<CRYPTO_set_locking_callback(3)|CRYPTO_set_locking_callback(3)>,
 L<ERR_get_error(3)|ERR_get_error(3)>,
 L<ERR_GET_LIB(3)|ERR_GET_LIB(3)>,
 L<ERR_clear_error(3)|ERR_clear_error(3)>,