Document ERR library.

=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

=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

=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

=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

=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