188 lines
6.6 KiB
Plaintext
188 lines
6.6 KiB
Plaintext
=pod
|
|
|
|
=head1 NAME
|
|
|
|
err - error codes
|
|
|
|
=head1 SYNOPSIS
|
|
|
|
#include <openssl/err.h>
|
|
|
|
unsigned long ERR_get_error(void);
|
|
unsigned long ERR_peek_error(void);
|
|
unsigned long ERR_get_error_line(const char **file, int *line);
|
|
unsigned long ERR_peek_error_line(const char **file, int *line);
|
|
unsigned long ERR_get_error_line_data(const char **file, int *line,
|
|
const char **data, int *flags);
|
|
unsigned long ERR_peek_error_line_data(const char **file, int *line,
|
|
const char **data, int *flags);
|
|
|
|
int ERR_GET_LIB(unsigned long e);
|
|
int ERR_GET_FUNC(unsigned long e);
|
|
int ERR_GET_REASON(unsigned long e);
|
|
|
|
void ERR_clear_error(void);
|
|
|
|
char *ERR_error_string(unsigned long e, char *buf);
|
|
const char *ERR_lib_error_string(unsigned long e);
|
|
const char *ERR_func_error_string(unsigned long e);
|
|
const char *ERR_reason_error_string(unsigned long e);
|
|
|
|
void ERR_print_errors(BIO *bp);
|
|
void ERR_print_errors_fp(FILE *fp);
|
|
|
|
void ERR_load_crypto_strings(void);
|
|
void ERR_free_strings(void);
|
|
|
|
void ERR_remove_state(unsigned long pid);
|
|
|
|
void ERR_put_error(int lib, int func, int reason, const char *file,
|
|
int line);
|
|
void ERR_add_error_data(int num, ...);
|
|
|
|
void ERR_load_strings(int lib,ERR_STRING_DATA str[]);
|
|
unsigned long ERR_PACK(int lib, int func, int reason);
|
|
int ERR_get_next_error_library(void);
|
|
|
|
=head1 DESCRIPTION
|
|
|
|
When a call to the OpenSSL library fails, this is usually signalled
|
|
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.
|
|
|
|
The L<ERR_get_error(3)|ERR_get_error(3)> manpage describes how to
|
|
access error codes.
|
|
|
|
Error codes contain information about where the error occurred, and
|
|
what went wrong. L<ERR_GET_LIB(3)|ERR_GET_LIB(3)> describes how to
|
|
extract this information. A method to obtain human-readable error
|
|
messages is described in L<ERR_error_string(3)|ERR_error_string(3)>.
|
|
|
|
L<ERR_clear_error(3)|ERR_clear_error(3)> can be used to clear the
|
|
error queue.
|
|
|
|
Note that L<ERR_remove_state(3)|ERR_remove_state(3)> should be used to
|
|
avoid memory leaks when threads are terminated.
|
|
|
|
=head1 ADDING NEW ERROR CODES TO OPENSSL
|
|
|
|
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 error codes to OpenSSL or add error codes from external libraries.
|
|
|
|
=head2 Reporting errors
|
|
|
|
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
|
|
"handshake failure" as follows:
|
|
|
|
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
|
|
B<ERR_LIB_XXX>, define a macro XXXerr() (both in B<err.h>), add its
|
|
name to B<ERR_str_libraries[]> (in B<crypto/err/err.c>), and add
|
|
C<ERR_load_XXX_strings()> to the ERR_load_crypto_strings() function
|
|
(in B<crypto/err/err_all.c>). Finally, add an entry
|
|
|
|
L XXX xxx.h xxx_err.c
|
|
|
|
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>
|
|
entry for each pid. ERR_get_state() returns the current thread's
|
|
B<ERR_STATE>. An B<ERR_STATE> can hold up to B<ERR_NUM_ERRORS> error
|
|
codes. When more error codes are added, the old ones are overwritten,
|
|
on the assumption that the most recent errors are most important.
|
|
|
|
Error strings are also stored in hash table. The hash tables can
|
|
be obtained by calling ERR_get_err_state_table(void) and
|
|
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)>,
|
|
L<ERR_error_string(3)|ERR_error_string(3)>,
|
|
L<ERR_print_errors(3)|ERR_print_errors(3)>,
|
|
L<ERR_load_crypto_strings(3)|ERR_load_crypto_strings(3)>,
|
|
L<ERR_remove_state(3)|ERR_remove_state(3)>,
|
|
L<ERR_put_error(3)|ERR_put_error(3)>,
|
|
L<ERR_load_strings(3)|ERR_load_strings(3)>,
|
|
L<SSL_get_error(3)|SSL_get_error(3)>
|
|
|
|
=cut
|