diff --git a/doc/crypto/ERR_GET_LIB.pod b/doc/crypto/ERR_GET_LIB.pod new file mode 100644 index 0000000000000000000000000000000000000000..2a129da036ccd97ac3695473cfdcd8cab930a701 --- /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 + + 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 reason codes such as B 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, L + +=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 0000000000000000000000000000000000000000..566e1f4e317fd9bce14982ff184301d150771aa8 --- /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 + + 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, L + +=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 0000000000000000000000000000000000000000..0d2417599cdace3fc4d64da95cf891b7240b062d --- /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 + + 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, and places it at B. B must be at least 120 +bytes long. If B is B, 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 is an 8 digit hexadecimal number, I, +I and I 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 or, for SSL +applications, L +first. +If there is no text string registered for the given error code, +the error string will contain the numeric code. + +L 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, B otherwise. + +ERR_lib_error_string(), ERR_func_error_string() and +ERR_reason_error_string() return the strings, and B if +none is registered for the error code. + +=head1 SEE ALSO + +L, L, +L, +L +L + +=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 0000000000000000000000000000000000000000..37259bfda1b9fc78755b0d1bed2cd3a38482f1aa --- /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 + + 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 for obtaining information about +location and reason of the error, and +L 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 and *B, unless these are B. + +ERR_get_error_line_data() and ERR_peek_error_line_data() store +additional data and flags associated with the error code in *B +and *B, unless these are B. *B contains a string +if *B&B. If it has been allocated by Malloc(), +*B&B is true. + +=head1 RETURN VALUES + +The error code, or 0 if there is no error in the queue. + +=head1 SEE ALSO + +L, L, +L + +=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 0000000000000000000000000000000000000000..25f7b2068040bb49f51f7f69cf01c7c2c11ae907 --- /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 + + void ERR_load_crypto_strings(void); + void ERR_free_strings(void); + + #include + + void SSL_load_error_strings(void); + +=head1 DESCRIPTION + +ERR_load_crypto_strings() registers the error strings for all +B functions. SSL_load_error_strings() does the same, +but also registers the B 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, L + +=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 0000000000000000000000000000000000000000..82c8e9c00e1b5c142d0229341c8ac3635b629a63 --- /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 + + 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. + +B 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 = ERR_PACK(B, B, B). +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, L + +=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 0000000000000000000000000000000000000000..b100a5fa2b30bf62949040f52036b4b2e4d4043e --- /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 + + 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, thus +emptying the error queue. + +ERR_print_errors_fp() is the same, except that the output goes to a +B. + + +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 is an 8 digit hexadecimal number. I, +I and I are ASCII text, as is I 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, L, +L, +L, +L + +=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 0000000000000000000000000000000000000000..b1cbbf026bf7dec4b56923b1eb59e649196cfc2e --- /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 + + 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 occurred in function +B of library B, in line number B of B. +This function is usually called by a macro. + +ERR_add_error_data() associates the concatenation of its B string +arguments with the error code added last. + +L 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, L + +=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 0000000000000000000000000000000000000000..cf7981e90721abd22821e5d194f306e7794247be --- /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 + + void ERR_remove_state(unsigned long pid); + +=head1 DESCRIPTION + +ERR_remove_state() frees the error queue associated with thread B. +If B == 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 + +=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 0000000000000000000000000000000000000000..5b0c4698cb765f30bb6cc828d2616add5db8047b --- /dev/null +++ b/doc/crypto/err.pod @@ -0,0 +1,130 @@ +=pod + +=head1 NAME + +err - Error codes + +=head1 SYNOPSIS + + #include + + 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 library provides +functions to obtain these error codes and textual error messages. + +The L manpage describes how to +access error codes. + +Error codes contain information about where the error occurred, and +what went wrong. L describes how to +extract this information. A method to obtain human-readable error +messages is described in L. + +L can be used to clear the +error queue. + +Note that L should be used to +avoid memory leaks when threads are terminated. + +=head1 ADDING NEW ERROR CODES TO OPENSSL + +See L 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, the second +argument is a reason code B. 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. +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, define a macro XXXerr() (both in B), add its +name to B (in B), and add +C to the ERR_load_crypto_strings() function +(in B). Finally, add an entry + + L XXX xxx.h xxx_err.c + +to B, and add B to the Makefile. +Running B will then generate a file B, and +add all error codes used in the library to B. + +=head1 INTERNALS + +The error queues are stored in a hash table with one B +entry for each pid. ERR_get_state() returns the current thread's +B. An B can hold up to B 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, +L, +L, +L, +L, +L, +L, +L, +L, +L + +=cut