test/Makefile: allow emulated test (e.g. under wine).

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

diff --git a/doc/crypto/err.pod b/doc/crypto/err.pod
index 5b0c4698cb765f30bb6cc828d2616add5db8047b..6f729554d2a9cc54fa8cb35513c518995945f14d 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
 
@@ -71,7 +71,7 @@ See L<ERR_put_error(3)> if you want to record error codes in the
 OpenSSL error system from within your application.
 
 The remainder of this section is of interest only if you want to add
-new functionality to OpenSSL.
+new error codes to OpenSSL or add error codes from external libraries.
 
 =head2 Reporting errors
 
@@ -84,10 +84,24 @@ descriptions. For example, the function ssl23_read() reports a
 
  SSLerr(SSL_F_SSL23_READ, 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 "SSL23_READ" 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
+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
 
 When adding a new sub-library to OpenSSL, assign it a library number
@@ -102,6 +116,47 @@ to B<crypto/err/openssl.ec>, and add B<xxx_err.c> to the Makefile.
 Running B<make errors> will then generate a file B<xxx_err.c>, and
 add all error codes used in the library to B<xxx.h>.
 
+Additionally the library include file must have a certain form.
+Typically it will initially look like this:
+
+ #ifndef HEADER_XXX_H
+ #define HEADER_XXX_H
+
+ #ifdef __cplusplus
+ extern "C" {
+ #endif
+
+ /* Include files */
+
+ #include <openssl/bio.h>
+ #include <openssl/x509.h>
+
+ /* Macros, structures and function prototypes */
+
+
+ /* BEGIN ERROR CODES */
+
+The B<BEGIN ERROR CODES> sequence is used by the error code
+generation script as the point to place new error codes, any text
+after this point will be overwritten when B<make errors> is run.
+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 containing any
+definitions it uses.
+
+=head1 USING ERROR CODES IN EXTERNAL LIBRARIES
+
+It is also possible to use OpenSSL's error code scheme in external
+libraries. The library needs to load its own codes and call the OpenSSL
+error code insertion script B<mkerr.pl> explicitly to add codes to
+the header file and generate the C error code file. This will normally
+be done if the external library needs to generate new ASN1 structures
+but it can also be used to add more general purpose error code handling.
+
+TBA more details
+
 =head1 INTERNALS
 
 The error queues are stored in a hash table with one B<ERR_STATE>
@@ -116,6 +171,8 @@ 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<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)>,