diff options
author | Ulf Möller <ulf@openssl.org> | 2000-02-01 01:37:00 +0000 |
---|---|---|
committer | Ulf Möller <ulf@openssl.org> | 2000-02-01 01:37:00 +0000 |
commit | 388f2f56f213dfada0370d48cb9bcc3c7e980b32 (patch) | |
tree | 587fe7258e54967024947b1da5c0851faf819276 /doc/crypto | |
parent | f5a8d67872fe2c58626a2423c3ec923f8c2a5d4a (diff) |
Document ERR library.
Diffstat (limited to 'doc/crypto')
-rw-r--r-- | doc/crypto/ERR_GET_LIB.pod | 51 | ||||
-rw-r--r-- | doc/crypto/ERR_clear_error.pod | 29 | ||||
-rw-r--r-- | doc/crypto/ERR_error_string.pod | 65 | ||||
-rw-r--r-- | doc/crypto/ERR_get_error.pod | 62 | ||||
-rw-r--r-- | doc/crypto/ERR_load_crypto_strings.pod | 46 | ||||
-rw-r--r-- | doc/crypto/ERR_load_strings.pod | 54 | ||||
-rw-r--r-- | doc/crypto/ERR_print_errors.pod | 51 | ||||
-rw-r--r-- | doc/crypto/ERR_put_error.pod | 44 | ||||
-rw-r--r-- | doc/crypto/ERR_remove_state.pod | 34 | ||||
-rw-r--r-- | doc/crypto/err.pod | 130 |
10 files changed, 566 insertions, 0 deletions
diff --git a/doc/crypto/ERR_GET_LIB.pod b/doc/crypto/ERR_GET_LIB.pod new file mode 100644 index 0000000000..2a129da036 --- /dev/null +++ b/doc/crypto/ERR_GET_LIB.pod @@ -0,0 +1,51 @@ +=pod + +=head1 NAME + +ERR_GET_LIB, ERR_GET_FUNC, ERR_GET_REASON - get library, function and +reason code + +=head1 SYNOPSIS + + #include <openssl/err.h> + + int ERR_GET_LIB(unsigned long e); + + int ERR_GET_FUNC(unsigned long e); + + int ERR_GET_REASON(unsigned long e); + +=head1 DESCRIPTION + +The error code returned by ERR_get_error() consists of a library +number, function code and reason code. ERR_GET_LIB(), ERR_GET_FUNC() +and ERR_GET_REASON() can be used to extract these. + +The library number and function code describe where the error +occurred, the reason code is the information about what went wrong. + +Each sub-library of OpenSSL has a unique library number; function and +reason codes are unique within each sub-library. Note that different +libraries may use the same value to signal different functions and +reasons. + +B<ERR_R_...> reason codes such as B<ERR_R_MALLOC_FAILURE> are globally +unique. However, when checking for sub-library specific reason codes, +be sure to also compare the library number. + +ERR_GET_LIB(), ERR_GET_FUNC() and ERR_GET_REASON() are macros. + +=head1 RETURN VALUES + +The library number, function code and reason code respectively. + +=head1 SEE ALSO + +L<err(3)|err(3)>, L<ERR_get_error(3)|ERR_get_error(3)> + +=head1 HISTORY + +ERR_GET_LIB(), ERR_GET_FUNC() and ERR_GET_REASON() are available in +all versions of SSLeay and OpenSSL. + +=cut diff --git a/doc/crypto/ERR_clear_error.pod b/doc/crypto/ERR_clear_error.pod new file mode 100644 index 0000000000..566e1f4e31 --- /dev/null +++ b/doc/crypto/ERR_clear_error.pod @@ -0,0 +1,29 @@ +=pod + +=head1 NAME + +ERR_clear_error - clear the error queue + +=head1 SYNOPSIS + + #include <openssl/err.h> + + void ERR_clear_error(void); + +=head1 DESCRIPTION + +ERR_clear_error() empties the current thread's error queue. + +=head1 RETURN VALUES + +ERR_clear_error() has no return value. + +=head1 SEE ALSO + +L<err(3)|err(3)>, L<ERR_get_error(3)|ERR_get_error(3)> + +=head1 HISTORY + +ERR_clear_error() is available in all versions of SSLeay and OpenSSL. + +=cut diff --git a/doc/crypto/ERR_error_string.pod b/doc/crypto/ERR_error_string.pod new file mode 100644 index 0000000000..0d2417599c --- /dev/null +++ b/doc/crypto/ERR_error_string.pod @@ -0,0 +1,65 @@ +=pod + +=head1 NAME + +ERR_error_string - obtain human-readable error message + +=head1 SYNOPSIS + + #include <openssl/err.h> + + 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); + +=head1 DESCRIPTION + +ERR_error_string() generates a human-readable string representing the +error code B<e>, and places it at B<buf>. B<buf> must be at least 120 +bytes long. If B<buf> is B<NULL>, the error string is placed in a +static buffer. + +The string will have the following format: + + error:[error code]:[library name]:[function name]:[reason string] + +I<error code> is an 8 digit hexadecimal number, I<library name>, +I<function name> and I<reason string> are ASCII text. + +ERR_lib_error_string(), ERR_func_error_string() and +ERR_reason_error_string() return the library name, function +name and reason string respectively. + +The OpenSSL error strings should be loaded by calling +L<ERR_load_crypto_strings(3)|ERR_load_crypto_strings(3)> or, for SSL +applications, L<SSL_load_error_strings(3)|SSL_load_error_strings(3)> +first. +If there is no text string registered for the given error code, +the error string will contain the numeric code. + +L<ERR_print_errors(3)|ERR_print_errors(3)> can be used to print +all error codes currently in the queue. + +=head1 RETURN VALUES + +ERR_error_string() returns a pointer to a static buffer containing the +string if B<buf == NULL>, B<buf> otherwise. + +ERR_lib_error_string(), ERR_func_error_string() and +ERR_reason_error_string() return the strings, and B<NULL> if +none is registered for the error code. + +=head1 SEE ALSO + +L<err(3)|err(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, +L<ERR_load_crypto_strings(3)|ERR_load_crypto_strings(3)>, +L<SSL_load_error_strings(3)|SSL_load_error_strings(3)> +L<ERR_print_errors(3)|ERR_print_errors(3)> + +=head1 HISTORY + +ERR_error_string() is available in all versions of SSLeay and OpenSSL. + +=cut diff --git a/doc/crypto/ERR_get_error.pod b/doc/crypto/ERR_get_error.pod new file mode 100644 index 0000000000..37259bfda1 --- /dev/null +++ b/doc/crypto/ERR_get_error.pod @@ -0,0 +1,62 @@ +=pod + +=head1 NAME + +ERR_get_error, ERR_peek_error - Obtain error code + +=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); + +=head1 DESCRIPTION + +ERR_get_error() returns the last error code from the thread's error +queue and removes the entry. This function can be called repeatedly +until there are no more error codes to return. + +ERR_peek_error() returns the last error code from the thread's +error queue without modifying it. + +See L<ERR_GET_LIB(3)|ERR_GET_LIB(3)> for obtaining information about +location and reason of the error, and +L<ERR_error_string(3)|ERR_error_string(3)> for human-readable error +messages. + +ERR_get_error_line() and ERR_peek_error_line() are the same as the +above, but they additionally store the file name and line number where +the error occurred in *B<file> and *B<line>, unless these are B<NULL>. + +ERR_get_error_line_data() and ERR_peek_error_line_data() store +additional data and flags associated with the error code in *B<data> +and *B<flags>, unless these are B<NULL>. *B<data> contains a string +if *B<flags>&B<ERR_TXT_STRING>. If it has been allocated by Malloc(), +*B<flags>&B<ERR_TXT_MALLOCED> is true. + +=head1 RETURN VALUES + +The error code, or 0 if there is no error in the queue. + +=head1 SEE ALSO + +L<err(3)|err(3)>, L<ERR_error_string(3)|ERR_error_string(3)>, +L<ERR_GET_LIB(3)|ERR_GET_LIB(3)> + +=head1 HISTORY + +ERR_get_error(), ERR_peek_error(), ERR_get_error_line() and +ERR_peek_error_line() are available in all versions of SSLeay and +OpenSSL. ERR_get_error_line_data() and ERR_peek_error_line_data() +were added in SSLeay 0.9.0. + +=cut diff --git a/doc/crypto/ERR_load_crypto_strings.pod b/doc/crypto/ERR_load_crypto_strings.pod new file mode 100644 index 0000000000..25f7b20680 --- /dev/null +++ b/doc/crypto/ERR_load_crypto_strings.pod @@ -0,0 +1,46 @@ +=pod + +=head1 NAME + +ERR_load_crypto_strings, SSL_load_error_strings, ERR_free_strings - +Load and free error strings + +=head1 SYNOPSIS + + #include <openssl/err.h> + + void ERR_load_crypto_strings(void); + void ERR_free_strings(void); + + #include <openssl/ssl.h> + + void SSL_load_error_strings(void); + +=head1 DESCRIPTION + +ERR_load_crypto_strings() registers the error strings for all +B<libcrypto> functions. SSL_load_error_strings() does the same, +but also registers the B<libssl> error strings. + +One of these functions should be called before generating +textual error messages. However, this is not required when memory +usage is an issue. + +ERR_free_strings() frees all previously loaded error strings. + +=head1 RETURN VALUES + +ERR_load_crypto_strings(), SSL_load_error_strings() and +ERR_free_strings() return no values. + +=head1 SEE ALSO + +L<err(3)|err(3)>, L<ERR_error_string(3)|ERR_error_string(3)> + +=head1 HISTORY + +ERR_load_error_strings(), SSL_load_error_strings() and +ERR_free_strings() are available in all versions of SSLeay and +OpenSSL. + +=cut diff --git a/doc/crypto/ERR_load_strings.pod b/doc/crypto/ERR_load_strings.pod new file mode 100644 index 0000000000..82c8e9c00e --- /dev/null +++ b/doc/crypto/ERR_load_strings.pod @@ -0,0 +1,54 @@ +=pod + +=head1 NAME + +ERR_load_strings, ERR_PACK, ERR_get_next_error_library - Load +arbitrary error strings + +=head1 SYNOPSIS + + #include <openssl/err.h> + + void ERR_load_strings(int lib, ERR_STRING_DATA str[]); + + int ERR_get_next_error_library(void); + + unsigned long ERR_PACK(int lib, int func, int reason); + +=head1 DESCRIPTION + +ERR_load_strings() registers error strings for library number B<lib>. + +B<str> is an array of error string data: + + typedef struct ERR_string_data_st + { + unsigned long error; + char *string; + } ERR_STRING_DATA; + +The error code is generated from the library number and a function and +reason code: B<error> = ERR_PACK(B<lib>, B<func>, B<reason>). +ERR_PACK() is a macro. + +The last entry in the array is {0,0}. + +ERR_get_next_error_library() can be used to assign library numbers +to user libraries at runtime. + +=head1 RETURN VALUE + +ERR_load_strings() returns no value. ERR_PACK() return the error code. +ERR_get_next_error_library() returns a new library number. + +=head1 SEE ALSO + +L<err(3)|err(3)>, L<ERR_load_strings(3)|ERR_load_strings(3)> + +=head1 HISTORY + +ERR_load_error_strings() and ERR_PACK() are available in all versions +of SSLeay and OpenSSL. ERR_get_next_error_library() was added in +SSLeay 0.9.0. + +=cut diff --git a/doc/crypto/ERR_print_errors.pod b/doc/crypto/ERR_print_errors.pod new file mode 100644 index 0000000000..b100a5fa2b --- /dev/null +++ b/doc/crypto/ERR_print_errors.pod @@ -0,0 +1,51 @@ +=pod + +=head1 NAME + +ERR_print_errors, ERR_print_errors_fp - print error messages + +=head1 SYNOPSIS + + #include <openssl/err.h> + + void ERR_print_errors(BIO *bp); + void ERR_print_errors_fp(FILE *fp); + +=head1 DESCRIPTION + +ERR_print_errors() is a convenience function that prints the error +strings for all errors that OpenSSL has recorded to B<bp>, thus +emptying the error queue. + +ERR_print_errors_fp() is the same, except that the output goes to a +B<FILE>. + + +The error strings will have the following format: + + [pid]:error:[error code]:[library name]:[function name]:[reason string]:[file name]:[line]:[optional text message] + +I<error code> is an 8 digit hexadecimal number. I<library name>, +I<function name> and I<reason string> are ASCII text, as is I<optional +text message> if one was set for the respective error code. + +If there is no text string registered for the given error code, +the error string will contain the numeric code. + +=head1 RETURN VALUES + +ERR_print_errors() and ERR_print_errors_fp() return no values. + +=head1 SEE ALSO + +L<err(3)|err(3)>, L<ERR_error_string(3)|ERR_error_string(3)>, +L<ERR_get_error(3)|ERR_get_error(3)>, +L<ERR_load_crypto_strings(3)|ERR_load_crypto_strings(3)>, +L<SSL_load_error_strings(3)|SSL_load_error_strings(3)> + +=head1 HISTORY + +ERR_print_errors() and ERR_print_errors_fp() +are available in all versions of SSLeay and OpenSSL. + +=cut diff --git a/doc/crypto/ERR_put_error.pod b/doc/crypto/ERR_put_error.pod new file mode 100644 index 0000000000..b1cbbf026b --- /dev/null +++ b/doc/crypto/ERR_put_error.pod @@ -0,0 +1,44 @@ +=pod + +=head1 NAME + +ERR_put_error, ERR_add_error_data - Record an error + +=head1 SYNOPSIS + + #include <openssl/err.h> + + void ERR_put_error(int lib, int func, int reason, const char *file, + int line); + + void ERR_add_error_data(int num, ...); + +=head1 DESCRIPTION + +ERR_put_error() adds an error code to the thread's error queue. It +signals that the error of reason code B<reason> occurred in function +B<func> of library B<lib>, in line number B<line> of B<file>. +This function is usually called by a macro. + +ERR_add_error_data() associates the concatenation of its B<num> string +arguments with the error code added last. + +L<ERR_load_strings(3)|ERR_load_strings(3)> can be used to register +error strings so that the application can a generate human-readable +error messages for the error code. + +=head1 RETURN VALUES + +ERR_put_error() and ERR_add_error_data() return +no values. + +=head1 SEE ALSO + +L<err(3)|err(3)>, L<ERR_load_strings(3)|ERR_load_strings(3)> + +=head1 HISTORY + +ERR_put_error() is available in all versions of SSLeay and OpenSSL. +ERR_add_error_data() was added in SSLeay 0.9.0. + +=cut diff --git a/doc/crypto/ERR_remove_state.pod b/doc/crypto/ERR_remove_state.pod new file mode 100644 index 0000000000..cf7981e907 --- /dev/null +++ b/doc/crypto/ERR_remove_state.pod @@ -0,0 +1,34 @@ +=pod + +=head1 NAME + +ERR_remove_state - Free a thread's error queue + +=head1 SYNOPSIS + + #include <openssl/err.h> + + void ERR_remove_state(unsigned long pid); + +=head1 DESCRIPTION + +ERR_remove_state() frees the error queue associated with thread B<pid>. +If B<pid> == 0, the current thread will have its error queue removed. + +Since error queue data structures are allocated automatically for new +threads, they must be freed when threads are terminated in oder to +avoid memory leaks. + +=head1 RETURN VALUE + +ERR_remove_state() returns no value. + +=head1 SEE ALSO + +L<err(3)|err(3)> + +=head1 HISTORY + +ERR_remove_state() is available in all versions of SSLeay and OpenSSL. + +=cut diff --git a/doc/crypto/err.pod b/doc/crypto/err.pod new file mode 100644 index 0000000000..5b0c4698cb --- /dev/null +++ b/doc/crypto/err.pod @@ -0,0 +1,130 @@ +=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 functionality to OpenSSL. + +=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); + +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. + +=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>. + +=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<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 |