Document ERR library.

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

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

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

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

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

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

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

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

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

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