From 878e440382fa65ddbadca1d2784ef1210f0ff652 Mon Sep 17 00:00:00 2001 From: schwarze <> Date: Wed, 2 Nov 2016 15:23:41 +0000 Subject: convert ERR manuals from pod to mdoc; while reading this, i wtfed, laughed, puked, and cried in more or less that order... --- src/lib/libcrypto/doc/ERR.pod | 185 -------------- src/lib/libcrypto/doc/ERR_GET_LIB.pod | 51 ---- src/lib/libcrypto/doc/ERR_clear_error.pod | 29 --- src/lib/libcrypto/doc/ERR_error_string.pod | 73 ------ src/lib/libcrypto/doc/ERR_get_error.pod | 79 ------ src/lib/libcrypto/doc/ERR_load_crypto_strings.pod | 46 ---- src/lib/libcrypto/doc/ERR_load_strings.pod | 54 ---- src/lib/libcrypto/doc/ERR_print_errors.pod | 51 ---- src/lib/libcrypto/doc/ERR_put_error.pod | 44 ---- src/lib/libcrypto/doc/ERR_remove_state.pod | 45 ---- src/lib/libcrypto/doc/ERR_set_mark.pod | 38 --- src/lib/libcrypto/man/ERR.3 | 297 ++++++++++++++++++++++ src/lib/libcrypto/man/ERR_GET_LIB.3 | 63 +++++ src/lib/libcrypto/man/ERR_clear_error.3 | 22 ++ src/lib/libcrypto/man/ERR_error_string.3 | 114 +++++++++ src/lib/libcrypto/man/ERR_get_error.3 | 135 ++++++++++ src/lib/libcrypto/man/ERR_load_crypto_strings.3 | 48 ++++ src/lib/libcrypto/man/ERR_load_strings.3 | 66 +++++ src/lib/libcrypto/man/ERR_print_errors.3 | 57 +++++ src/lib/libcrypto/man/ERR_put_error.3 | 58 +++++ src/lib/libcrypto/man/ERR_remove_state.3 | 58 +++++ src/lib/libcrypto/man/ERR_set_mark.3 | 35 +++ src/lib/libcrypto/man/Makefile | 20 +- 23 files changed, 963 insertions(+), 705 deletions(-) delete mode 100644 src/lib/libcrypto/doc/ERR.pod delete mode 100644 src/lib/libcrypto/doc/ERR_GET_LIB.pod delete mode 100644 src/lib/libcrypto/doc/ERR_clear_error.pod delete mode 100644 src/lib/libcrypto/doc/ERR_error_string.pod delete mode 100644 src/lib/libcrypto/doc/ERR_get_error.pod delete mode 100644 src/lib/libcrypto/doc/ERR_load_crypto_strings.pod delete mode 100644 src/lib/libcrypto/doc/ERR_load_strings.pod delete mode 100644 src/lib/libcrypto/doc/ERR_print_errors.pod delete mode 100644 src/lib/libcrypto/doc/ERR_put_error.pod delete mode 100644 src/lib/libcrypto/doc/ERR_remove_state.pod delete mode 100644 src/lib/libcrypto/doc/ERR_set_mark.pod create mode 100644 src/lib/libcrypto/man/ERR.3 create mode 100644 src/lib/libcrypto/man/ERR_GET_LIB.3 create mode 100644 src/lib/libcrypto/man/ERR_clear_error.3 create mode 100644 src/lib/libcrypto/man/ERR_error_string.3 create mode 100644 src/lib/libcrypto/man/ERR_get_error.3 create mode 100644 src/lib/libcrypto/man/ERR_load_crypto_strings.3 create mode 100644 src/lib/libcrypto/man/ERR_load_strings.3 create mode 100644 src/lib/libcrypto/man/ERR_print_errors.3 create mode 100644 src/lib/libcrypto/man/ERR_put_error.3 create mode 100644 src/lib/libcrypto/man/ERR_remove_state.3 create mode 100644 src/lib/libcrypto/man/ERR_set_mark.3 diff --git a/src/lib/libcrypto/doc/ERR.pod b/src/lib/libcrypto/doc/ERR.pod deleted file mode 100644 index 343a9b84c2..0000000000 --- a/src/lib/libcrypto/doc/ERR.pod +++ /dev/null @@ -1,185 +0,0 @@ -=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 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, 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); - -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. -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, 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. - -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 - #include - - /* Macros, structures and function prototypes */ - - - /* BEGIN ERROR CODES */ - -The B 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 is run. -The closing #endif etc will be automatically added by the script. - -The generated C error code file B will load the header -files B, B and B 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 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. - -=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, -L, -L - -=cut diff --git a/src/lib/libcrypto/doc/ERR_GET_LIB.pod b/src/lib/libcrypto/doc/ERR_GET_LIB.pod deleted file mode 100644 index 2a129da036..0000000000 --- a/src/lib/libcrypto/doc/ERR_GET_LIB.pod +++ /dev/null @@ -1,51 +0,0 @@ -=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/src/lib/libcrypto/doc/ERR_clear_error.pod b/src/lib/libcrypto/doc/ERR_clear_error.pod deleted file mode 100644 index 566e1f4e31..0000000000 --- a/src/lib/libcrypto/doc/ERR_clear_error.pod +++ /dev/null @@ -1,29 +0,0 @@ -=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/src/lib/libcrypto/doc/ERR_error_string.pod b/src/lib/libcrypto/doc/ERR_error_string.pod deleted file mode 100644 index cdfa7fe1fe..0000000000 --- a/src/lib/libcrypto/doc/ERR_error_string.pod +++ /dev/null @@ -1,73 +0,0 @@ -=pod - -=head1 NAME - -ERR_error_string, ERR_error_string_n, ERR_lib_error_string, -ERR_func_error_string, ERR_reason_error_string - obtain human-readable -error message - -=head1 SYNOPSIS - - #include - - char *ERR_error_string(unsigned long e, char *buf); - void ERR_error_string_n(unsigned long e, char *buf, size_t len); - - 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 I, and places it at I. I must be at least 120 -bytes long. If I is B, the error string is placed in a -static buffer. -ERR_error_string_n() is a variant of ERR_error_string() that writes -at most I characters (including the terminating 0) -and truncates the string if necessary. -For ERR_error_string_n(), I may not be B. - -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 I B<== NULL>, I 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. -ERR_error_string_n() was added in OpenSSL 0.9.6. - -=cut diff --git a/src/lib/libcrypto/doc/ERR_get_error.pod b/src/lib/libcrypto/doc/ERR_get_error.pod deleted file mode 100644 index 460a79f3f6..0000000000 --- a/src/lib/libcrypto/doc/ERR_get_error.pod +++ /dev/null @@ -1,79 +0,0 @@ -=pod - -=head1 NAME - -ERR_get_error, ERR_peek_error, ERR_peek_last_error, -ERR_get_error_line, ERR_peek_error_line, ERR_peek_last_error_line, -ERR_get_error_line_data, ERR_peek_error_line_data, -ERR_peek_last_error_line_data - obtain error code and data - -=head1 SYNOPSIS - - #include - - unsigned long ERR_get_error(void); - unsigned long ERR_peek_error(void); - unsigned long ERR_peek_last_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_peek_last_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); - unsigned long ERR_peek_last_error_line_data(const char **file, int *line, - const char **data, int *flags); - -=head1 DESCRIPTION - -ERR_get_error() returns the earliest 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 earliest error code from the thread's -error queue without modifying it. - -ERR_peek_last_error() returns the latest 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(), ERR_peek_error_line() and -ERR_peek_last_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(), ERR_peek_error_line_data() and -ERR_peek_last_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 is true. - -An application B free the *B pointer (or any other pointers -returned by these functions) with free() as freeing is handled -automatically by the error library. - -=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. -ERR_peek_last_error(), ERR_peek_last_error_line() and -ERR_peek_last_error_line_data() were added in OpenSSL 0.9.7. - -=cut diff --git a/src/lib/libcrypto/doc/ERR_load_crypto_strings.pod b/src/lib/libcrypto/doc/ERR_load_crypto_strings.pod deleted file mode 100644 index 9bdec75a46..0000000000 --- a/src/lib/libcrypto/doc/ERR_load_crypto_strings.pod +++ /dev/null @@ -1,46 +0,0 @@ -=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/src/lib/libcrypto/doc/ERR_load_strings.pod b/src/lib/libcrypto/doc/ERR_load_strings.pod deleted file mode 100644 index e9c5cf0fc5..0000000000 --- a/src/lib/libcrypto/doc/ERR_load_strings.pod +++ /dev/null @@ -1,54 +0,0 @@ -=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_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/src/lib/libcrypto/doc/ERR_print_errors.pod b/src/lib/libcrypto/doc/ERR_print_errors.pod deleted file mode 100644 index b100a5fa2b..0000000000 --- a/src/lib/libcrypto/doc/ERR_print_errors.pod +++ /dev/null @@ -1,51 +0,0 @@ -=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/src/lib/libcrypto/doc/ERR_put_error.pod b/src/lib/libcrypto/doc/ERR_put_error.pod deleted file mode 100644 index acd241fbe4..0000000000 --- a/src/lib/libcrypto/doc/ERR_put_error.pod +++ /dev/null @@ -1,44 +0,0 @@ -=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/src/lib/libcrypto/doc/ERR_remove_state.pod b/src/lib/libcrypto/doc/ERR_remove_state.pod deleted file mode 100644 index a4d38c17fd..0000000000 --- a/src/lib/libcrypto/doc/ERR_remove_state.pod +++ /dev/null @@ -1,45 +0,0 @@ -=pod - -=head1 NAME - -ERR_remove_thread_state, ERR_remove_state - free a thread's error queue - -=head1 SYNOPSIS - - #include - - void ERR_remove_thread_state(const CRYPTO_THREADID *tid); - -Deprecated: - - void ERR_remove_state(unsigned long pid); - -=head1 DESCRIPTION - -ERR_remove_thread_state() frees the error queue associated with thread B. -If B == B, 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 order to -avoid memory leaks. - -ERR_remove_state is deprecated and has been replaced by -ERR_remove_thread_state. Since threads in OpenSSL are no longer identified -by unsigned long values any argument to this function is ignored. Calling -ERR_remove_state is equivalent to B. - -=head1 RETURN VALUE - -ERR_remove_thread_state and ERR_remove_state() return no value. - -=head1 SEE ALSO - -L - -=head1 HISTORY - -ERR_remove_state() is available in all versions of SSLeay and OpenSSL. It -was deprecated in OpenSSL 1.0.0 when ERR_remove_thread_state was introduced -and thread IDs were introduced to identify threads instead of 'unsigned long'. - -=cut diff --git a/src/lib/libcrypto/doc/ERR_set_mark.pod b/src/lib/libcrypto/doc/ERR_set_mark.pod deleted file mode 100644 index d3ca4f2e77..0000000000 --- a/src/lib/libcrypto/doc/ERR_set_mark.pod +++ /dev/null @@ -1,38 +0,0 @@ -=pod - -=head1 NAME - -ERR_set_mark, ERR_pop_to_mark - set marks and pop errors until mark - -=head1 SYNOPSIS - - #include - - int ERR_set_mark(void); - - int ERR_pop_to_mark(void); - -=head1 DESCRIPTION - -ERR_set_mark() sets a mark on the current topmost error record if there -is one. - -ERR_pop_to_mark() will pop the top of the error stack until a mark is found. -The mark is then removed. If there is no mark, the whole stack is removed. - -=head1 RETURN VALUES - -ERR_set_mark() returns 0 if the error stack is empty, otherwise 1. - -ERR_pop_to_mark() returns 0 if there was no mark in the error stack, which -implies that the stack became empty, otherwise 1. - -=head1 SEE ALSO - -L - -=head1 HISTORY - -ERR_set_mark() and ERR_pop_to_mark() were added in OpenSSL 0.9.8. - -=cut diff --git a/src/lib/libcrypto/man/ERR.3 b/src/lib/libcrypto/man/ERR.3 new file mode 100644 index 0000000000..2c9a4479f7 --- /dev/null +++ b/src/lib/libcrypto/man/ERR.3 @@ -0,0 +1,297 @@ +.Dd $Mdocdate: November 2 2016 $ +.Dt ERR 3 +.Os +.Sh NAME +.Nm ERR +.Nd OpenSSL error codes +.Sh SYNOPSIS +.In openssl/err.h +.Ft unsigned long +.Fn ERR_get_error void +.Ft unsigned long +.Fn ERR_peek_error void +.Ft unsigned long +.Fo ERR_get_error_line +.Fa "const char **file" +.Fa "int *line" +.Fc +.Ft unsigned long +.Fo ERR_peek_error_line +.Fa "const char **file" +.Fa "int *line" +.Fc +.Ft unsigned long +.Fo ERR_get_error_line_data +.Fa "const char **file" +.Fa "int *line" +.Fa "const char **data" +.Fa "int *flags" +.Fc +.Ft unsigned long +.Fo ERR_peek_error_line_data +.Fa "const char **file" +.Fa "int *line" +.Fa "const char **data" +.Fa "int *flags" +.Fc +.Ft int +.Fo ERR_GET_LIB +.Fa "unsigned long e" +.Fc +.Ft int +.Fo ERR_GET_FUNC +.Fa "unsigned long e" +.Fc +.Ft int +.Fo ERR_GET_REASON +.Fa "unsigned long e" +.Fc +.Ft void +.Fn ERR_clear_error void +.Ft char * +.Fo ERR_error_string +.Fa "unsigned long e" +.Fa "char *buf" +.Fc +.Ft const char * +.Fo ERR_lib_error_string +.Fa "unsigned long e" +.Fc +.Ft const char * +.Fo ERR_func_error_string +.Fa "unsigned long e" +.Fc +.Ft const char * +.Fo ERR_reason_error_string +.Fa "unsigned long e" +.Fc +.Ft void +.Fo ERR_print_errors +.Fa "BIO *bp" +.Fc +.Ft void +.Fo ERR_print_errors_fp +.Fa "FILE *fp" +.Fc +.Ft void +.Fn ERR_load_crypto_strings void +.Ft void +.Fn ERR_free_strings void +.Ft void +.Fo ERR_remove_state +.Fa "unsigned long pid" +.Fc +.Ft void +.Fo ERR_put_error +.Fa "int lib" +.Fa "int func" +.Fa "int reason" +.Fa "const char *file" +.Fa "int line" +.Fc +.Ft void +.Fo ERR_add_error_data +.Fa "int num" +.Fa ... +.Fc +.Ft void +.Fo ERR_load_strings +.Fa "int lib" +.Fa "ERR_STRING_DATA str[]" +.Fc +.Ft unsigned long +.Fo ERR_PACK +.Fa "int lib" +.Fa "int func" +.Fa "int reason" +.Fc +.Ft int +.Fn ERR_get_next_error_library void +.Sh 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 +.Nm +library provides functions to obtain these error codes and textual error +messages. +The +.Xr ERR_get_error 3 +manpage describes how to access error codes. +.Pp +Error codes contain information about where the error occurred, and what +went wrong. +.Xr ERR_GET_LIB 3 +describes how to extract this information. +A method to obtain human-readable error messages is described in +.Xr ERR_error_string 3 . +.Pp +.Xr ERR_clear_error 3 +can be used to clear the error queue. +.Pp +Note that +.Xr ERR_remove_state 3 +should be used to avoid memory leaks when threads are terminated. +.Sh ADDING NEW ERROR CODES TO OPENSSL +See +.Xr ERR_put_error 3 +if you want to record error codes in the OpenSSL error system from +within your application. +.Pp +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. +.Ss Reporting errors +Each sub-library has a specific macro +.Fn XXXerr f r +that is used to report errors. +Its first argument is a function code +.Dv XXX_F_* , +the second argument is a reason code +.Dv XXX_R_* . +Function codes are derived from the function names; reason codes consist +of textual error descriptions. +For example, the function +.Fn ssl23_read +reports a "handshake failure" as follows: +.Pp +.Dl SSLerr(SSL_F_SSL23_READ, SSL_R_SSL_HANDSHAKE_FAILURE); +.Pp +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. +.Pp +The trailing section of a reason code (after the "_R_") is translated +into lower case and underscores changed to spaces. +.Pp +When you are using new function or reason codes, run +.Sy make errors . +The necessary +.Sy #define Ns s +will then automatically be added to the sub-library's header file. +.Pp +Although a library will normally report errors using its own specific +.Fn 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 +.Fn ASN1err +macro. +.Ss Adding new libraries +When adding a new sub-library to OpenSSL, assign it a library number +.Dv ERR_LIB_XXX , +define a macro +.Fn XXXerr +(both in +.In openssl/err.h ) , +add its name to +.Va ERR_str_libraries[] +(in +.Pa /usr/src/lib/libcrypto/err/err.c ) , +and add +.Fn ERR_load_XXX_strings +to the +.Fn ERR_load_crypto_strings +function (in +.Sy /usr/src/lib/libcrypto/err/err_all.c ) . +Finally, add an entry +.Pp +.Dl L XXX xxx.h xxx_err.c +.Pp +to +.Sy /usr/src/lib/libcrypto/err/openssl.ec , +and add +.Pa xxx_err.c +to the +.Pa Makefile . +Running +.Sy make errors +will then generate a file +.Pa xxx_err.c , +and add all error codes used in the library to +.Pa xxx.h . +.Pp +Additionally the library include file must have a certain form. +Typically it will initially look like this: +.Bd -literal -offset indent +#ifndef HEADER_XXX_H +#define HEADER_XXX_H + +#ifdef __cplusplus +extern "C" { +#endif + +/* Include files */ + +#include +#include + +/* Macros, structures and function prototypes */ + +/* BEGIN ERROR CODES */ +.Ed +.Pp +The +.Sy 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 +.Sy make errors +is run. +The closing #endif etc. will be automatically added by the script. +.Pp +The generated C error code file +.Pa xxx_err.c +will load the header files +.In stdio.h , +.In openssl/err.h +and +.In openssl/xxx.h +so the header file must load any additional header files containing any +definitions it uses. +.Sh 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 +.Pa 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. +.Sh INTERNALS +The error queues are stored in a hash table with one +.Vt ERR_STATE +entry for each pid. +.Fn ERR_get_state +returns the current thread's +.Vt ERR_STATE . +An +.Vt ERR_STATE +can hold up to +.Dv 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. +.Pp +Error strings are also stored in hash table. +The hash tables can be obtained by calling +.Fn ERR_get_err_state_table +and +.Fn ERR_get_string_table . +.Sh SEE ALSO +.Xr CRYPTO_set_id_callback 3 , +.Xr CRYPTO_set_locking_callback 3 , +.Xr ERR_clear_error 3 , +.Xr ERR_error_string 3 , +.Xr ERR_get_error 3 , +.Xr ERR_GET_LIB 3 , +.Xr ERR_load_crypto_strings 3 , +.Xr ERR_load_strings 3 , +.Xr ERR_print_errors 3 , +.Xr ERR_put_error 3 , +.Xr ERR_remove_state 3 , +.Xr SSL_get_error 3 diff --git a/src/lib/libcrypto/man/ERR_GET_LIB.3 b/src/lib/libcrypto/man/ERR_GET_LIB.3 new file mode 100644 index 0000000000..9b50ce39e6 --- /dev/null +++ b/src/lib/libcrypto/man/ERR_GET_LIB.3 @@ -0,0 +1,63 @@ +.Dd $Mdocdate: November 2 2016 $ +.Dt ERR_GET_LIB 3 +.Os +.Sh NAME +.Nm ERR_GET_LIB , +.Nm ERR_GET_FUNC , +.Nm ERR_GET_REASON +.Nd get library, function and reason codes for OpenSSL errors +.Sh SYNOPSIS +.In openssl/err.h +.Ft int +.Fo ERR_GET_LIB +.Fa "unsigned long e" +.Fc +.Ft int +.Fo ERR_GET_FUNC +.Fa "unsigned long e" +.Fc +.Ft int +.Fo ERR_GET_REASON +.Fa "unsigned long e" +.Fc +.Sh DESCRIPTION +The error code returned by +.Xr ERR_get_error 3 +consists of a library number, function code, and reason code. +.Fn ERR_GET_LIB , +.Fn ERR_GET_FUNC , +and +.Fn ERR_GET_REASON +can be used to extract these. +.Pp +The library number and function code describe where the error occurred, +the reason code is the information about what went wrong. +.Pp +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. +.Pp +.Dv ERR_R_* +reason codes such as +.Dv ERR_R_MALLOC_FAILURE +are globally unique. +However, when checking for sub-library specific reason codes, be sure to +also compare the library number. +.Pp +.Fn ERR_GET_LIB , +.Fn ERR_GET_FUNC , +and +.Fn ERR_GET_REASON +are macros. +.Sh RETURN VALUES +The library number, function code, and reason code, respectively. +.Sh SEE ALSO +.Xr ERR 3 , +.Xr ERR_get_error 3 +.Sh HISTORY +.Fn ERR_GET_LIB , +.Fn ERR_GET_FUNC , +and +.Fn ERR_GET_REASON +are available in all versions of SSLeay and OpenSSL. diff --git a/src/lib/libcrypto/man/ERR_clear_error.3 b/src/lib/libcrypto/man/ERR_clear_error.3 new file mode 100644 index 0000000000..f5beb14b10 --- /dev/null +++ b/src/lib/libcrypto/man/ERR_clear_error.3 @@ -0,0 +1,22 @@ +.Dd $Mdocdate: November 2 2016 $ +.Dt ERR_CLEAR_ERROR 3 +.Os +.Sh NAME +.Nm ERR_clear_error +.Nd clear the OpenSSL error queue +.Sh SYNOPSIS +.In openssl/err.h +.Ft void +.Fn ERR_clear_error void +.Sh DESCRIPTION +.Fn ERR_clear_error +empties the current thread's error queue. +.Sh RETURN VALUES +.Fn ERR_clear_error +has no return value. +.Sh SEE ALSO +.Xr ERR 3 , +.Xr ERR_get_error 3 +.Sh HISTORY +.Fn ERR_clear_error +is available in all versions of SSLeay and OpenSSL. diff --git a/src/lib/libcrypto/man/ERR_error_string.3 b/src/lib/libcrypto/man/ERR_error_string.3 new file mode 100644 index 0000000000..75878d233e --- /dev/null +++ b/src/lib/libcrypto/man/ERR_error_string.3 @@ -0,0 +1,114 @@ +.Dd $Mdocdate: November 2 2016 $ +.Dt ERR_ERROR_STRING 3 +.Os +.Sh NAME +.Nm ERR_error_string , +.Nm ERR_error_string_n , +.Nm ERR_lib_error_string , +.Nm ERR_func_error_string , +.Nm ERR_reason_error_string +.Nd obtain human-readable OpenSSL error messages +.Sh SYNOPSIS +.In openssl/err.h +.Ft char * +.Fo ERR_error_string +.Fa "unsigned long e" +.Fa "char *buf" +.Fc +.Ft void +.Fo ERR_error_string_n +.Fa "unsigned long e" +.Fa "char *buf" +.Fa "size_t len" +.Fc +.Ft const char * +.Fo ERR_lib_error_string +.Fa "unsigned long e" +.Fc +.Ft const char * +.Fo ERR_func_error_string +.Fa "unsigned long e" +.Fc +.Ft const char * +.Fo ERR_reason_error_string +.Fa "unsigned long e" +.Fc +.Sh DESCRIPTION +.Fn ERR_error_string +generates a human-readable string representing the error code +.Fa e +and places it in +.Fa buf . +.Fa buf +must be at least 120 bytes long. +If +.Fa buf +is +.Dv NULL , +the error string is placed in a static buffer. +.Fn ERR_error_string_n +is a variant of +.Fn ERR_error_string +that writes at most +.Fa len +characters (including the terminating NUL) and truncates the string +if necessary. +For +.Fn ERR_error_string_n , +.Fa buf +may not be +.Dv NULL . +.Pp +The string will have the following format: +.Pp +.Dl error:[error code]:[library name]:[function name]:[reason string] +.Pp +The error code is an 8 digit hexadecimal number. +The library name, the function name, and the reason string are ASCII +text. +.Pp +.Fn ERR_lib_error_string , +.Fn ERR_func_error_string , +and +.Fn ERR_reason_error_string +return the library name, the function name, and the reason string, +respectively. +.Pp +The OpenSSL error strings should be loaded by calling +.Xr ERR_load_crypto_strings 3 +or, for SSL applications, +.Xr 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. +.Pp +.Xr ERR_print_errors 3 +can be used to print all error codes currently in the queue. +.Sh RETURN VALUES +.Fn ERR_error_string +returns a pointer to a static buffer containing the string if +.Fa buf +is +.Dv NULL , +or +.Fa buf +otherwise. +.Pp +.Fn ERR_lib_error_string , +.Fn ERR_func_error_string , +and +.Fn ERR_reason_error_string +return the strings, or +.Dv NULL +if none is registered for the error code. +.Sh SEE ALSO +.Xr ERR 3 , +.Xr ERR_get_error 3 , +.Xr ERR_load_crypto_strings 3 , +.Xr ERR_print_errors 3 , +.Xr SSL_load_error_strings 3 +.Sh HISTORY +.Fn ERR_error_string +is available in all versions of SSLeay and OpenSSL. +.Fn ERR_error_string_n +was added in OpenSSL 0.9.6. diff --git a/src/lib/libcrypto/man/ERR_get_error.3 b/src/lib/libcrypto/man/ERR_get_error.3 new file mode 100644 index 0000000000..8b11f792c1 --- /dev/null +++ b/src/lib/libcrypto/man/ERR_get_error.3 @@ -0,0 +1,135 @@ +.Dd $Mdocdate: November 2 2016 $ +.Dt ERR_GET_ERROR 3 +.Os +.Sh NAME +.Nm ERR_get_error , +.Nm ERR_peek_error , +.Nm ERR_peek_last_error , +.Nm ERR_get_error_line , +.Nm ERR_peek_error_line , +.Nm ERR_peek_last_error_line , +.Nm ERR_get_error_line_data , +.Nm ERR_peek_error_line_data , +.Nm ERR_peek_last_error_line_data +.Nd obtain OpenSSL error code and data +.Sh SYNOPSIS +.In openssl/err.h +.Ft unsigned long +.Fn ERR_get_error void +.Ft unsigned long +.Fn ERR_peek_error void +.Ft unsigned long +.Fn ERR_peek_last_error void +.Ft unsigned long +.Fo ERR_get_error_line +.Fa "const char **file" +.Fa "int *line" +.Fc +.Ft unsigned long +.Fo ERR_peek_error_line +.Fa "const char **file" +.Fa "int *line" +.Fc +.Ft unsigned long +.Fo ERR_peek_last_error_line +.Fa "const char **file" +.Fa "int *line" +.Fc +.Ft unsigned long +.Fo ERR_get_error_line_data +.Fa "const char **file" +.Fa "int *line" +.Fa "const char **data" +.Fa "int *flags" +.Fc +.Ft unsigned long +.Fo ERR_peek_error_line_data +.Fa "const char **file" +.Fa "int *line" +.Fa "const char **data" +.Fa "int *flags" +.Fc +.Ft unsigned long +.Fo ERR_peek_last_error_line_data +.Fa "const char **file" +.Fa "int *line" +.Fa "const char **data" +.Fa "int *flags" +.Fc +.Sh DESCRIPTION +.Fn ERR_get_error +returns the earliest 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. +.Pp +.Fn ERR_peek_error +returns the earliest error code from the thread's error queue without +modifying it. +.Pp +.Fn ERR_peek_last_error +returns the latest error code from the thread's error queue without +modifying it. +.Pp +See +.Xr ERR_GET_LIB 3 +for obtaining information about location and reason of the error, and +.Xr ERR_error_string 3 +for human-readable error messages. +.Pp +.Fn ERR_get_error_line , +.Fn ERR_peek_error_line , +and +.Fn ERR_peek_last_error_line +are the same as the above, but they additionally store the file name and +line number where the error occurred in +.Pf * Fa file +and +.Pf * Fa line , +unless these are +.Dv NULL . +.Pp +.Fn ERR_get_error_line_data , +.Fn ERR_peek_error_line_data , +and +.Fn ERR_peek_last_error_line_data +store additional data and flags associated with the error code in +.Pf * Fa data +and +.Pf * Fa flags , +unless these are +.Dv NULL . +.Pf * Fa data +contains a string if +.Pf * Fa flags Ns & Ns Dv ERR_TXT_STRING +is true. +.Pp +An application +.Sy MUST NOT +free the +.Pf * Fa data +pointer (or any other pointers returned by these functions) with +.Xr free 3 +as freeing is handled automatically by the error library. +.Sh RETURN VALUES +The error code, or 0 if there is no error in the queue. +.Sh SEE ALSO +.Xr ERR 3 , +.Xr ERR_error_string 3 , +.Xr ERR_GET_LIB 3 +.Sh HISTORY +.Fn ERR_get_error , +.Fn ERR_peek_error , +.Fn ERR_get_error_line , +and +.Fn ERR_peek_error_line +are available in all versions of SSLeay and OpenSSL. +.Fn ERR_get_error_line_data +and +.Fn ERR_peek_error_line_data +were added in SSLeay 0.9.0. +.Fn ERR_peek_last_error , +.Fn ERR_peek_last_error_line , +and +.Fn ERR_peek_last_error_line_data +were added in OpenSSL 0.9.7. diff --git a/src/lib/libcrypto/man/ERR_load_crypto_strings.3 b/src/lib/libcrypto/man/ERR_load_crypto_strings.3 new file mode 100644 index 0000000000..7d14b1e572 --- /dev/null +++ b/src/lib/libcrypto/man/ERR_load_crypto_strings.3 @@ -0,0 +1,48 @@ +.Dd $Mdocdate: November 2 2016 $ +.Dt ERR_LOAD_CRYPTO_STRINGS 3 +.Os +.Sh NAME +.Nm ERR_load_crypto_strings , +.Nm SSL_load_error_strings , +.Nm ERR_free_strings +.Nd load and free OpenSSL error strings +.Sh SYNOPSIS +.In openssl/err.h +.Ft void +.Fn ERR_load_crypto_strings void +.Ft void +.Fn ERR_free_strings void +.In openssl/ssl.h +.Ft void +.Fn SSL_load_error_strings void +.Sh DESCRIPTION +.Fn ERR_load_crypto_strings +registers the error strings for all +.Xr crypto 3 +functions. +.Fn SSL_load_error_strings +does the same, but also registers the +.Xr ssl 3 +error strings. +.Pp +One of these functions should be called before generating textual error +messages. +However, this is not required when memory usage is an issue. +.Pp +.Fn ERR_free_strings +frees all previously loaded error strings. +.Sh RETURN VALUES +.Fn ERR_load_crypto_strings , +.Fn SSL_load_error_strings , +and +.Fn ERR_free_strings +return no values. +.Sh SEE ALSO +.Xr ERR 3 , +.Xr ERR_error_string 3 +.Sh HISTORY +.Xr ERR_load_error_strings 3 , +.Fn SSL_load_error_strings , +and +.Fn ERR_free_strings +are available in all versions of SSLeay and OpenSSL. diff --git a/src/lib/libcrypto/man/ERR_load_strings.3 b/src/lib/libcrypto/man/ERR_load_strings.3 new file mode 100644 index 0000000000..691a4067d3 --- /dev/null +++ b/src/lib/libcrypto/man/ERR_load_strings.3 @@ -0,0 +1,66 @@ +.Dd $Mdocdate: November 2 2016 $ +.Dt ERR_LOAD_STRINGS 3 +.Os +.Sh NAME +.Nm ERR_load_strings , +.Nm ERR_PACK , +.Nm ERR_get_next_error_library +.Nd load arbitrary OpenSSL error strings +.Sh SYNOPSIS +.In openssl/err.h +.Ft void +.Fo ERR_load_strings +.Fa "int lib" +.Fa "ERR_STRING_DATA str[]" +.Fc +.Ft int +.Fn ERR_get_next_error_library void +.Ft unsigned long +.Fo ERR_PACK +.Fa "int lib" +.Fa "int func" +.Fa "int reason" +.Fc +.Sh DESCRIPTION +.Fn ERR_load_strings +registers error strings for library number +.Fa lib . +.Pp +.Fa str +is an array of error string data: +.Bd -literal -offset indent +typedef struct ERR_string_data_st +{ + unsigned long error; + char *string; +} ERR_STRING_DATA; +.Ed +.Pp +The error code is generated from the library number and a function and +reason code: +.Pp +.Dl error = ERR_PACK(lib, func, reason) +.Pp +.Fn ERR_PACK +is a macro. +.Pp +The last entry in the array is +.Brq 0 , Dv NULL . +.Pp +.Fn ERR_get_next_error_library +can be used to assign library numbers to user libraries at runtime. +.Sh RETURN VALUE +.Fn ERR_PACK +returns the error code. +.Fn ERR_get_next_error_library +returns a new library number. +.Sh SEE ALSO +.Xr ERR 3 , +.Xr ERR_load_strings 3 +.Sh HISTORY +.Xr ERR_load_error_strings 3 +and +.Fn ERR_PACK +are available in all versions of SSLeay and OpenSSL. +.Fn ERR_get_next_error_library +was added in SSLeay 0.9.0. diff --git a/src/lib/libcrypto/man/ERR_print_errors.3 b/src/lib/libcrypto/man/ERR_print_errors.3 new file mode 100644 index 0000000000..1fc80d93f7 --- /dev/null +++ b/src/lib/libcrypto/man/ERR_print_errors.3 @@ -0,0 +1,57 @@ +.Dd $Mdocdate: November 2 2016 $ +.Dt ERR_PRINT_ERRORS 3 +.Os +.Sh NAME +.Nm ERR_print_errors , +.Nm ERR_print_errors_fp +.Nd print OpenSSL error messages +.Sh SYNOPSIS +.In openssl/err.h +.Ft void +.Fo ERR_print_errors +.Fa "BIO *bp" +.Fc +.Ft void +.Fo ERR_print_errors_fp +.Fa "FILE *fp" +.Fc +.Sh DESCRIPTION +.Fn ERR_print_errors +is a convenience function that prints the error strings for all errors +that OpenSSL has recorded to +.Fa bp , +thus emptying the error queue. +.Pp +.Fn ERR_print_errors_fp +is the same, except that the output goes to a +.Vt FILE . +.Pp +The error strings have the following format: +.Bd -literal +[pid]:error:[error code]:[library name]:[function name]:[reason string]: +[file name]:[line]:[optional text message] +.Ed +.Pp +The error code is an 8 digit hexadecimal number. +The library name, the function name, and the reason string are ASCII +text, as is the optional text message if one was set for the +respective error code. +.Pp +If there is no text string registered for the given error code, the +error string will contain the numeric code. +.Sh RETURN VALUES +.Fn ERR_print_errors +and +.Fn ERR_print_errors_fp +return no values. +.Sh SEE ALSO +.Xr ERR 3 , +.Xr ERR_error_string 3 , +.Xr ERR_get_error 3 , +.Xr ERR_load_crypto_strings 3 , +.Xr SSL_load_error_strings 3 +.Sh HISTORY +.Fn ERR_print_errors +and +.Fn ERR_print_errors_fp +are available in all versions of SSLeay and OpenSSL. diff --git a/src/lib/libcrypto/man/ERR_put_error.3 b/src/lib/libcrypto/man/ERR_put_error.3 new file mode 100644 index 0000000000..703b74d713 --- /dev/null +++ b/src/lib/libcrypto/man/ERR_put_error.3 @@ -0,0 +1,58 @@ +.Dd $Mdocdate: November 2 2016 $ +.Dt ERR_PUT_ERROR 3 +.Os +.Sh NAME +.Nm ERR_put_error , +.Nm ERR_add_error_data +.Nd record an OpenSSL error +.Sh SYNOPSIS +.In openssl/err.h +.Ft void +.Fo ERR_put_error +.Fa "int lib" +.Fa "int func" +.Fa "int reason" +.Fa "const char *file" +.Fa "int line" +.Fc +.Ft void +.Fo ERR_add_error_data +.Fa "int num" +.Fa ... +.Fc +.Sh DESCRIPTION +.Fn ERR_put_error +adds an error code to the thread's error queue. +It signals that the error of reason code +.Fa reason +occurred in function +.Fa func +of library +.Fa lib , +in line number +.Fa line +of +.Fa file . +This function is usually called by a macro. +.Pp +.Fn ERR_add_error_data +associates the concatenation of its +.Fa num +string arguments with the error code added last. +.Pp +.Xr 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. +.Sh RETURN VALUES +.Fn ERR_put_error +and +.Fn ERR_add_error_data +return no values. +.Sh SEE ALSO +.Xr ERR 3 , +.Xr ERR_load_strings 3 +.Sh HISTORY +.Fn ERR_put_error +is available in all versions of SSLeay and OpenSSL. +.Fn ERR_add_error_data +was added in SSLeay 0.9.0. diff --git a/src/lib/libcrypto/man/ERR_remove_state.3 b/src/lib/libcrypto/man/ERR_remove_state.3 new file mode 100644 index 0000000000..c15779edfc --- /dev/null +++ b/src/lib/libcrypto/man/ERR_remove_state.3 @@ -0,0 +1,58 @@ +.Dd $Mdocdate: November 2 2016 $ +.Dt ERR_REMOVE_STATE 3 +.Os +.Sh NAME +.Nm ERR_remove_thread_state , +.Nm ERR_remove_state +.Nd free a thread's OpenSSL error queue +.Sh SYNOPSIS +.In openssl/err.h +.Ft void +.Fo ERR_remove_thread_state +.Fa "const CRYPTO_THREADID *tid" +.Fc +.Pp +Deprecated: +.Pp +.Ft void +.Fo ERR_remove_state +.Fa "unsigned long pid" +.Fc +.Sh DESCRIPTION +.Fn ERR_remove_thread_state +frees the error queue associated with thread +.Fa tid . +If +.Fa tid +is +.Dv NULL , +the current thread will have its error queue removed. +.Pp +Since error queue data structures are allocated automatically for new +threads, they must be freed when threads are terminated in order to +avoid memory leaks. +.Pp +.Fn ERR_remove_state +is deprecated and has been replaced by +.Fn ERR_remove_thread_state . +Since threads in OpenSSL are no longer identified by unsigned long +values, any argument to this function is ignored. +Calling +.Fn ERR_remove_state +is equivalent to +.Fn ERR_remove_thread_state NULL . +.Sh RETURN VALUE +.Fn ERR_remove_thread_state +and +.Fn ERR_remove_state +return no value. +.Sh SEE ALSO +.Xr ERR 3 +.Sh HISTORY +.Fn ERR_remove_state +is available in all versions of SSLeay and OpenSSL. +It was deprecated in OpenSSL 1.0.0 when +.Fn ERR_remove_thread_state +was introduced and thread IDs were introduced to identify threads +instead of +.Vt unsigned long . diff --git a/src/lib/libcrypto/man/ERR_set_mark.3 b/src/lib/libcrypto/man/ERR_set_mark.3 new file mode 100644 index 0000000000..e268271418 --- /dev/null +++ b/src/lib/libcrypto/man/ERR_set_mark.3 @@ -0,0 +1,35 @@ +.Dd $Mdocdate: November 2 2016 $ +.Dt ERR_SET_MARK 3 +.Os +.Sh NAME +.Nm ERR_set_mark , +.Nm ERR_pop_to_mark +.Nd set marks and pop OpenSSL errors until mark +.Sh SYNOPSIS +.In openssl/err.h +.Ft int +.Fn ERR_set_mark void +.Ft int +.Fn ERR_pop_to_mark void +.Sh DESCRIPTION +.Fn ERR_set_mark +sets a mark on the current topmost error record if there is one. +.Pp +.Fn ERR_pop_to_mark +will pop the top of the error stack until a mark is found. +The mark is then removed. +If there is no mark, the whole stack is removed. +.Sh RETURN VALUES +.Fn ERR_set_mark +returns 0 if the error stack is empty, otherwise 1. +.Pp +.Fn ERR_pop_to_mark +returns 0 if there was no mark in the error stack, which implies that +the stack became empty, otherwise 1. +.Sh SEE ALSO +.Xr ERR 3 +.Sh HISTORY +.Fn ERR_set_mark +and +.Fn ERR_pop_to_mark +were added in OpenSSL 0.9.8. diff --git a/src/lib/libcrypto/man/Makefile b/src/lib/libcrypto/man/Makefile index f676472ff6..5d19e023ab 100644 --- a/src/lib/libcrypto/man/Makefile +++ b/src/lib/libcrypto/man/Makefile @@ -1,4 +1,4 @@ -# $OpenBSD: Makefile,v 1.36 2016/11/02 11:57:56 schwarze Exp $ +# $OpenBSD: Makefile,v 1.37 2016/11/02 15:23:41 schwarze Exp $ .include # for NOMAN @@ -80,15 +80,6 @@ MAN= \ EC_POINT_add.3 \ EC_POINT_new.3 \ ECDSA_SIG_new.3 \ - EVP_AEAD_CTX_init.3 \ - UI_new.3 \ - bn_dump.3 \ - crypto.3 \ - d2i_PKCS8PrivateKey_bio.3 \ - des_read_pw.3 \ - lh_new.3 \ - -GENMAN= \ ERR.3 \ ERR_GET_LIB.3 \ ERR_clear_error.3 \ @@ -100,6 +91,15 @@ GENMAN= \ ERR_put_error.3 \ ERR_remove_state.3 \ ERR_set_mark.3 \ + EVP_AEAD_CTX_init.3 \ + UI_new.3 \ + bn_dump.3 \ + crypto.3 \ + d2i_PKCS8PrivateKey_bio.3 \ + des_read_pw.3 \ + lh_new.3 \ + +GENMAN= \ EVP_BytesToKey.3 \ EVP_DigestInit.3 \ EVP_DigestSignInit.3 \ -- cgit v1.2.3-55-g6feb