summaryrefslogtreecommitdiff
path: root/src
diff options
context:
space:
mode:
Diffstat (limited to 'src')
-rw-r--r--src/lib/libcrypto/doc/ERR.pod185
-rw-r--r--src/lib/libcrypto/doc/ERR_GET_LIB.pod51
-rw-r--r--src/lib/libcrypto/doc/ERR_clear_error.pod29
-rw-r--r--src/lib/libcrypto/doc/ERR_error_string.pod73
-rw-r--r--src/lib/libcrypto/doc/ERR_get_error.pod79
-rw-r--r--src/lib/libcrypto/doc/ERR_load_crypto_strings.pod46
-rw-r--r--src/lib/libcrypto/doc/ERR_load_strings.pod54
-rw-r--r--src/lib/libcrypto/doc/ERR_print_errors.pod51
-rw-r--r--src/lib/libcrypto/doc/ERR_put_error.pod44
-rw-r--r--src/lib/libcrypto/doc/ERR_remove_state.pod45
-rw-r--r--src/lib/libcrypto/doc/ERR_set_mark.pod38
-rw-r--r--src/lib/libcrypto/man/ERR.3297
-rw-r--r--src/lib/libcrypto/man/ERR_GET_LIB.363
-rw-r--r--src/lib/libcrypto/man/ERR_clear_error.322
-rw-r--r--src/lib/libcrypto/man/ERR_error_string.3114
-rw-r--r--src/lib/libcrypto/man/ERR_get_error.3135
-rw-r--r--src/lib/libcrypto/man/ERR_load_crypto_strings.348
-rw-r--r--src/lib/libcrypto/man/ERR_load_strings.366
-rw-r--r--src/lib/libcrypto/man/ERR_print_errors.357
-rw-r--r--src/lib/libcrypto/man/ERR_put_error.358
-rw-r--r--src/lib/libcrypto/man/ERR_remove_state.358
-rw-r--r--src/lib/libcrypto/man/ERR_set_mark.335
-rw-r--r--src/lib/libcrypto/man/Makefile20
23 files changed, 963 insertions, 705 deletions
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 @@
1=pod
2
3=head1 NAME
4
5ERR - error codes
6
7=head1 SYNOPSIS
8
9 #include <openssl/err.h>
10
11 unsigned long ERR_get_error(void);
12 unsigned long ERR_peek_error(void);
13 unsigned long ERR_get_error_line(const char **file, int *line);
14 unsigned long ERR_peek_error_line(const char **file, int *line);
15 unsigned long ERR_get_error_line_data(const char **file, int *line,
16 const char **data, int *flags);
17 unsigned long ERR_peek_error_line_data(const char **file, int *line,
18 const char **data, int *flags);
19
20 int ERR_GET_LIB(unsigned long e);
21 int ERR_GET_FUNC(unsigned long e);
22 int ERR_GET_REASON(unsigned long e);
23
24 void ERR_clear_error(void);
25
26 char *ERR_error_string(unsigned long e, char *buf);
27 const char *ERR_lib_error_string(unsigned long e);
28 const char *ERR_func_error_string(unsigned long e);
29 const char *ERR_reason_error_string(unsigned long e);
30
31 void ERR_print_errors(BIO *bp);
32 void ERR_print_errors_fp(FILE *fp);
33
34 void ERR_load_crypto_strings(void);
35 void ERR_free_strings(void);
36
37 void ERR_remove_state(unsigned long pid);
38
39 void ERR_put_error(int lib, int func, int reason, const char *file,
40 int line);
41 void ERR_add_error_data(int num, ...);
42
43 void ERR_load_strings(int lib,ERR_STRING_DATA str[]);
44 unsigned long ERR_PACK(int lib, int func, int reason);
45 int ERR_get_next_error_library(void);
46
47=head1 DESCRIPTION
48
49When a call to the OpenSSL library fails, this is usually signalled
50by the return value, and an error code is stored in an error queue
51associated with the current thread. The B<err> library provides
52functions to obtain these error codes and textual error messages.
53
54The L<ERR_get_error(3)|ERR_get_error(3)> manpage describes how to
55access error codes.
56
57Error codes contain information about where the error occurred, and
58what went wrong. L<ERR_GET_LIB(3)|ERR_GET_LIB(3)> describes how to
59extract this information. A method to obtain human-readable error
60messages is described in L<ERR_error_string(3)|ERR_error_string(3)>.
61
62L<ERR_clear_error(3)|ERR_clear_error(3)> can be used to clear the
63error queue.
64
65Note that L<ERR_remove_state(3)|ERR_remove_state(3)> should be used to
66avoid memory leaks when threads are terminated.
67
68=head1 ADDING NEW ERROR CODES TO OPENSSL
69
70See L<ERR_put_error(3)> if you want to record error codes in the
71OpenSSL error system from within your application.
72
73The remainder of this section is of interest only if you want to add
74new error codes to OpenSSL or add error codes from external libraries.
75
76=head2 Reporting errors
77
78Each sub-library has a specific macro XXXerr() that is used to report
79errors. Its first argument is a function code B<XXX_F_...>, the second
80argument is a reason code B<XXX_R_...>. Function codes are derived
81from the function names; reason codes consist of textual error
82descriptions. For example, the function ssl23_read() reports a
83"handshake failure" as follows:
84
85 SSLerr(SSL_F_SSL23_READ, SSL_R_SSL_HANDSHAKE_FAILURE);
86
87Function and reason codes should consist of upper case characters,
88numbers and underscores only. The error file generation script translates
89function codes into function names by looking in the header files
90for an appropriate function name, if none is found it just uses
91the capitalized form such as "SSL23_READ" in the above example.
92
93The trailing section of a reason code (after the "_R_") is translated
94into lower case and underscores changed to spaces.
95
96When you are using new function or reason codes, run B<make errors>.
97The necessary B<#define>s will then automatically be added to the
98sub-library's header file.
99
100Although a library will normally report errors using its own specific
101XXXerr macro, another library's macro can be used. This is normally
102only done when a library wants to include ASN1 code which must use
103the ASN1err() macro.
104
105=head2 Adding new libraries
106
107When adding a new sub-library to OpenSSL, assign it a library number
108B<ERR_LIB_XXX>, define a macro XXXerr() (both in B<err.h>), add its
109name to B<ERR_str_libraries[]> (in B<crypto/err/err.c>), and add
110C<ERR_load_XXX_strings()> to the ERR_load_crypto_strings() function
111(in B<crypto/err/err_all.c>). Finally, add an entry
112
113 L XXX xxx.h xxx_err.c
114
115to B<crypto/err/openssl.ec>, and add B<xxx_err.c> to the Makefile.
116Running B<make errors> will then generate a file B<xxx_err.c>, and
117add all error codes used in the library to B<xxx.h>.
118
119Additionally the library include file must have a certain form.
120Typically it will initially look like this:
121
122 #ifndef HEADER_XXX_H
123 #define HEADER_XXX_H
124
125 #ifdef __cplusplus
126 extern "C" {
127 #endif
128
129 /* Include files */
130
131 #include <openssl/bio.h>
132 #include <openssl/x509.h>
133
134 /* Macros, structures and function prototypes */
135
136
137 /* BEGIN ERROR CODES */
138
139The B<BEGIN ERROR CODES> sequence is used by the error code
140generation script as the point to place new error codes, any text
141after this point will be overwritten when B<make errors> is run.
142The closing #endif etc will be automatically added by the script.
143
144The generated C error code file B<xxx_err.c> will load the header
145files B<stdio.h>, B<openssl/err.h> and B<openssl/xxx.h> so the
146header file must load any additional header files containing any
147definitions it uses.
148
149=head1 USING ERROR CODES IN EXTERNAL LIBRARIES
150
151It is also possible to use OpenSSL's error code scheme in external
152libraries. The library needs to load its own codes and call the OpenSSL
153error code insertion script B<mkerr.pl> explicitly to add codes to
154the header file and generate the C error code file. This will normally
155be done if the external library needs to generate new ASN1 structures
156but it can also be used to add more general purpose error code handling.
157
158=head1 INTERNALS
159
160The error queues are stored in a hash table with one B<ERR_STATE>
161entry for each pid. ERR_get_state() returns the current thread's
162B<ERR_STATE>. An B<ERR_STATE> can hold up to B<ERR_NUM_ERRORS> error
163codes. When more error codes are added, the old ones are overwritten,
164on the assumption that the most recent errors are most important.
165
166Error strings are also stored in hash table. The hash tables can
167be obtained by calling ERR_get_err_state_table(void) and
168ERR_get_string_table(void) respectively.
169
170=head1 SEE ALSO
171
172L<CRYPTO_set_id_callback(3)|CRYPTO_set_id_callback(3)>,
173L<CRYPTO_set_locking_callback(3)|CRYPTO_set_locking_callback(3)>,
174L<ERR_get_error(3)|ERR_get_error(3)>,
175L<ERR_GET_LIB(3)|ERR_GET_LIB(3)>,
176L<ERR_clear_error(3)|ERR_clear_error(3)>,
177L<ERR_error_string(3)|ERR_error_string(3)>,
178L<ERR_print_errors(3)|ERR_print_errors(3)>,
179L<ERR_load_crypto_strings(3)|ERR_load_crypto_strings(3)>,
180L<ERR_remove_state(3)|ERR_remove_state(3)>,
181L<ERR_put_error(3)|ERR_put_error(3)>,
182L<ERR_load_strings(3)|ERR_load_strings(3)>,
183L<SSL_get_error(3)|SSL_get_error(3)>
184
185=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 @@
1=pod
2
3=head1 NAME
4
5ERR_GET_LIB, ERR_GET_FUNC, ERR_GET_REASON - get library, function and
6reason code
7
8=head1 SYNOPSIS
9
10 #include <openssl/err.h>
11
12 int ERR_GET_LIB(unsigned long e);
13
14 int ERR_GET_FUNC(unsigned long e);
15
16 int ERR_GET_REASON(unsigned long e);
17
18=head1 DESCRIPTION
19
20The error code returned by ERR_get_error() consists of a library
21number, function code and reason code. ERR_GET_LIB(), ERR_GET_FUNC()
22and ERR_GET_REASON() can be used to extract these.
23
24The library number and function code describe where the error
25occurred, the reason code is the information about what went wrong.
26
27Each sub-library of OpenSSL has a unique library number; function and
28reason codes are unique within each sub-library. Note that different
29libraries may use the same value to signal different functions and
30reasons.
31
32B<ERR_R_...> reason codes such as B<ERR_R_MALLOC_FAILURE> are globally
33unique. However, when checking for sub-library specific reason codes,
34be sure to also compare the library number.
35
36ERR_GET_LIB(), ERR_GET_FUNC() and ERR_GET_REASON() are macros.
37
38=head1 RETURN VALUES
39
40The library number, function code and reason code respectively.
41
42=head1 SEE ALSO
43
44L<err(3)|err(3)>, L<ERR_get_error(3)|ERR_get_error(3)>
45
46=head1 HISTORY
47
48ERR_GET_LIB(), ERR_GET_FUNC() and ERR_GET_REASON() are available in
49all versions of SSLeay and OpenSSL.
50
51=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 @@
1=pod
2
3=head1 NAME
4
5ERR_clear_error - clear the error queue
6
7=head1 SYNOPSIS
8
9 #include <openssl/err.h>
10
11 void ERR_clear_error(void);
12
13=head1 DESCRIPTION
14
15ERR_clear_error() empties the current thread's error queue.
16
17=head1 RETURN VALUES
18
19ERR_clear_error() has no return value.
20
21=head1 SEE ALSO
22
23L<err(3)|err(3)>, L<ERR_get_error(3)|ERR_get_error(3)>
24
25=head1 HISTORY
26
27ERR_clear_error() is available in all versions of SSLeay and OpenSSL.
28
29=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 @@
1=pod
2
3=head1 NAME
4
5ERR_error_string, ERR_error_string_n, ERR_lib_error_string,
6ERR_func_error_string, ERR_reason_error_string - obtain human-readable
7error message
8
9=head1 SYNOPSIS
10
11 #include <openssl/err.h>
12
13 char *ERR_error_string(unsigned long e, char *buf);
14 void ERR_error_string_n(unsigned long e, char *buf, size_t len);
15
16 const char *ERR_lib_error_string(unsigned long e);
17 const char *ERR_func_error_string(unsigned long e);
18 const char *ERR_reason_error_string(unsigned long e);
19
20=head1 DESCRIPTION
21
22ERR_error_string() generates a human-readable string representing the
23error code I<e>, and places it at I<buf>. I<buf> must be at least 120
24bytes long. If I<buf> is B<NULL>, the error string is placed in a
25static buffer.
26ERR_error_string_n() is a variant of ERR_error_string() that writes
27at most I<len> characters (including the terminating 0)
28and truncates the string if necessary.
29For ERR_error_string_n(), I<buf> may not be B<NULL>.
30
31The string will have the following format:
32
33 error:[error code]:[library name]:[function name]:[reason string]
34
35I<error code> is an 8 digit hexadecimal number, I<library name>,
36I<function name> and I<reason string> are ASCII text.
37
38ERR_lib_error_string(), ERR_func_error_string() and
39ERR_reason_error_string() return the library name, function
40name and reason string respectively.
41
42The OpenSSL error strings should be loaded by calling
43L<ERR_load_crypto_strings(3)|ERR_load_crypto_strings(3)> or, for SSL
44applications, L<SSL_load_error_strings(3)|SSL_load_error_strings(3)>
45first.
46If there is no text string registered for the given error code,
47the error string will contain the numeric code.
48
49L<ERR_print_errors(3)|ERR_print_errors(3)> can be used to print
50all error codes currently in the queue.
51
52=head1 RETURN VALUES
53
54ERR_error_string() returns a pointer to a static buffer containing the
55string if I<buf> B<== NULL>, I<buf> otherwise.
56
57ERR_lib_error_string(), ERR_func_error_string() and
58ERR_reason_error_string() return the strings, and B<NULL> if
59none is registered for the error code.
60
61=head1 SEE ALSO
62
63L<err(3)|err(3)>, L<ERR_get_error(3)|ERR_get_error(3)>,
64L<ERR_load_crypto_strings(3)|ERR_load_crypto_strings(3)>,
65L<SSL_load_error_strings(3)|SSL_load_error_strings(3)>
66L<ERR_print_errors(3)|ERR_print_errors(3)>
67
68=head1 HISTORY
69
70ERR_error_string() is available in all versions of SSLeay and OpenSSL.
71ERR_error_string_n() was added in OpenSSL 0.9.6.
72
73=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 @@
1=pod
2
3=head1 NAME
4
5ERR_get_error, ERR_peek_error, ERR_peek_last_error,
6ERR_get_error_line, ERR_peek_error_line, ERR_peek_last_error_line,
7ERR_get_error_line_data, ERR_peek_error_line_data,
8ERR_peek_last_error_line_data - obtain error code and data
9
10=head1 SYNOPSIS
11
12 #include <openssl/err.h>
13
14 unsigned long ERR_get_error(void);
15 unsigned long ERR_peek_error(void);
16 unsigned long ERR_peek_last_error(void);
17
18 unsigned long ERR_get_error_line(const char **file, int *line);
19 unsigned long ERR_peek_error_line(const char **file, int *line);
20 unsigned long ERR_peek_last_error_line(const char **file, int *line);
21
22 unsigned long ERR_get_error_line_data(const char **file, int *line,
23 const char **data, int *flags);
24 unsigned long ERR_peek_error_line_data(const char **file, int *line,
25 const char **data, int *flags);
26 unsigned long ERR_peek_last_error_line_data(const char **file, int *line,
27 const char **data, int *flags);
28
29=head1 DESCRIPTION
30
31ERR_get_error() returns the earliest error code from the thread's error
32queue and removes the entry. This function can be called repeatedly
33until there are no more error codes to return.
34
35ERR_peek_error() returns the earliest error code from the thread's
36error queue without modifying it.
37
38ERR_peek_last_error() returns the latest error code from the thread's
39error queue without modifying it.
40
41See L<ERR_GET_LIB(3)|ERR_GET_LIB(3)> for obtaining information about
42location and reason of the error, and
43L<ERR_error_string(3)|ERR_error_string(3)> for human-readable error
44messages.
45
46ERR_get_error_line(), ERR_peek_error_line() and
47ERR_peek_last_error_line() are the same as the above, but they
48additionally store the file name and line number where
49the error occurred in *B<file> and *B<line>, unless these are B<NULL>.
50
51ERR_get_error_line_data(), ERR_peek_error_line_data() and
52ERR_peek_last_error_line_data() store additional data and flags
53associated with the error code in *B<data>
54and *B<flags>, unless these are B<NULL>. *B<data> contains a string
55if *B<flags>&B<ERR_TXT_STRING> is true.
56
57An application B<MUST NOT> free the *B<data> pointer (or any other pointers
58returned by these functions) with free() as freeing is handled
59automatically by the error library.
60
61=head1 RETURN VALUES
62
63The error code, or 0 if there is no error in the queue.
64
65=head1 SEE ALSO
66
67L<err(3)|err(3)>, L<ERR_error_string(3)|ERR_error_string(3)>,
68L<ERR_GET_LIB(3)|ERR_GET_LIB(3)>
69
70=head1 HISTORY
71
72ERR_get_error(), ERR_peek_error(), ERR_get_error_line() and
73ERR_peek_error_line() are available in all versions of SSLeay and
74OpenSSL. ERR_get_error_line_data() and ERR_peek_error_line_data()
75were added in SSLeay 0.9.0.
76ERR_peek_last_error(), ERR_peek_last_error_line() and
77ERR_peek_last_error_line_data() were added in OpenSSL 0.9.7.
78
79=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 @@
1=pod
2
3=head1 NAME
4
5ERR_load_crypto_strings, SSL_load_error_strings, ERR_free_strings -
6load and free error strings
7
8=head1 SYNOPSIS
9
10 #include <openssl/err.h>
11
12 void ERR_load_crypto_strings(void);
13 void ERR_free_strings(void);
14
15 #include <openssl/ssl.h>
16
17 void SSL_load_error_strings(void);
18
19=head1 DESCRIPTION
20
21ERR_load_crypto_strings() registers the error strings for all
22B<libcrypto> functions. SSL_load_error_strings() does the same,
23but also registers the B<libssl> error strings.
24
25One of these functions should be called before generating
26textual error messages. However, this is not required when memory
27usage is an issue.
28
29ERR_free_strings() frees all previously loaded error strings.
30
31=head1 RETURN VALUES
32
33ERR_load_crypto_strings(), SSL_load_error_strings() and
34ERR_free_strings() return no values.
35
36=head1 SEE ALSO
37
38L<err(3)|err(3)>, L<ERR_error_string(3)|ERR_error_string(3)>
39
40=head1 HISTORY
41
42ERR_load_error_strings(), SSL_load_error_strings() and
43ERR_free_strings() are available in all versions of SSLeay and
44OpenSSL.
45
46=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 @@
1=pod
2
3=head1 NAME
4
5ERR_load_strings, ERR_PACK, ERR_get_next_error_library - load
6arbitrary error strings
7
8=head1 SYNOPSIS
9
10 #include <openssl/err.h>
11
12 void ERR_load_strings(int lib, ERR_STRING_DATA str[]);
13
14 int ERR_get_next_error_library(void);
15
16 unsigned long ERR_PACK(int lib, int func, int reason);
17
18=head1 DESCRIPTION
19
20ERR_load_strings() registers error strings for library number B<lib>.
21
22B<str> is an array of error string data:
23
24 typedef struct ERR_string_data_st
25 {
26 unsigned long error;
27 char *string;
28 } ERR_STRING_DATA;
29
30The error code is generated from the library number and a function and
31reason code: B<error> = ERR_PACK(B<lib>, B<func>, B<reason>).
32ERR_PACK() is a macro.
33
34The last entry in the array is {0,0}.
35
36ERR_get_next_error_library() can be used to assign library numbers
37to user libraries at runtime.
38
39=head1 RETURN VALUE
40
41ERR_PACK() return the error code.
42ERR_get_next_error_library() returns a new library number.
43
44=head1 SEE ALSO
45
46L<err(3)|err(3)>, L<ERR_load_strings(3)|ERR_load_strings(3)>
47
48=head1 HISTORY
49
50ERR_load_error_strings() and ERR_PACK() are available in all versions
51of SSLeay and OpenSSL. ERR_get_next_error_library() was added in
52SSLeay 0.9.0.
53
54=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 @@
1=pod
2
3=head1 NAME
4
5ERR_print_errors, ERR_print_errors_fp - print error messages
6
7=head1 SYNOPSIS
8
9 #include <openssl/err.h>
10
11 void ERR_print_errors(BIO *bp);
12 void ERR_print_errors_fp(FILE *fp);
13
14=head1 DESCRIPTION
15
16ERR_print_errors() is a convenience function that prints the error
17strings for all errors that OpenSSL has recorded to B<bp>, thus
18emptying the error queue.
19
20ERR_print_errors_fp() is the same, except that the output goes to a
21B<FILE>.
22
23
24The error strings will have the following format:
25
26 [pid]:error:[error code]:[library name]:[function name]:[reason string]:[file name]:[line]:[optional text message]
27
28I<error code> is an 8 digit hexadecimal number. I<library name>,
29I<function name> and I<reason string> are ASCII text, as is I<optional
30text message> if one was set for the respective error code.
31
32If there is no text string registered for the given error code,
33the error string will contain the numeric code.
34
35=head1 RETURN VALUES
36
37ERR_print_errors() and ERR_print_errors_fp() return no values.
38
39=head1 SEE ALSO
40
41L<err(3)|err(3)>, L<ERR_error_string(3)|ERR_error_string(3)>,
42L<ERR_get_error(3)|ERR_get_error(3)>,
43L<ERR_load_crypto_strings(3)|ERR_load_crypto_strings(3)>,
44L<SSL_load_error_strings(3)|SSL_load_error_strings(3)>
45
46=head1 HISTORY
47
48ERR_print_errors() and ERR_print_errors_fp()
49are available in all versions of SSLeay and OpenSSL.
50
51=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 @@
1=pod
2
3=head1 NAME
4
5ERR_put_error, ERR_add_error_data - record an error
6
7=head1 SYNOPSIS
8
9 #include <openssl/err.h>
10
11 void ERR_put_error(int lib, int func, int reason, const char *file,
12 int line);
13
14 void ERR_add_error_data(int num, ...);
15
16=head1 DESCRIPTION
17
18ERR_put_error() adds an error code to the thread's error queue. It
19signals that the error of reason code B<reason> occurred in function
20B<func> of library B<lib>, in line number B<line> of B<file>.
21This function is usually called by a macro.
22
23ERR_add_error_data() associates the concatenation of its B<num> string
24arguments with the error code added last.
25
26L<ERR_load_strings(3)|ERR_load_strings(3)> can be used to register
27error strings so that the application can a generate human-readable
28error messages for the error code.
29
30=head1 RETURN VALUES
31
32ERR_put_error() and ERR_add_error_data() return
33no values.
34
35=head1 SEE ALSO
36
37L<err(3)|err(3)>, L<ERR_load_strings(3)|ERR_load_strings(3)>
38
39=head1 HISTORY
40
41ERR_put_error() is available in all versions of SSLeay and OpenSSL.
42ERR_add_error_data() was added in SSLeay 0.9.0.
43
44=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 @@
1=pod
2
3=head1 NAME
4
5ERR_remove_thread_state, ERR_remove_state - free a thread's error queue
6
7=head1 SYNOPSIS
8
9 #include <openssl/err.h>
10
11 void ERR_remove_thread_state(const CRYPTO_THREADID *tid);
12
13Deprecated:
14
15 void ERR_remove_state(unsigned long pid);
16
17=head1 DESCRIPTION
18
19ERR_remove_thread_state() frees the error queue associated with thread B<tid>.
20If B<tid> == B<NULL>, the current thread will have its error queue removed.
21
22Since error queue data structures are allocated automatically for new
23threads, they must be freed when threads are terminated in order to
24avoid memory leaks.
25
26ERR_remove_state is deprecated and has been replaced by
27ERR_remove_thread_state. Since threads in OpenSSL are no longer identified
28by unsigned long values any argument to this function is ignored. Calling
29ERR_remove_state is equivalent to B<ERR_remove_thread_state(NULL)>.
30
31=head1 RETURN VALUE
32
33ERR_remove_thread_state and ERR_remove_state() return no value.
34
35=head1 SEE ALSO
36
37L<err(3)|err(3)>
38
39=head1 HISTORY
40
41ERR_remove_state() is available in all versions of SSLeay and OpenSSL. It
42was deprecated in OpenSSL 1.0.0 when ERR_remove_thread_state was introduced
43and thread IDs were introduced to identify threads instead of 'unsigned long'.
44
45=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 @@
1=pod
2
3=head1 NAME
4
5ERR_set_mark, ERR_pop_to_mark - set marks and pop errors until mark
6
7=head1 SYNOPSIS
8
9 #include <openssl/err.h>
10
11 int ERR_set_mark(void);
12
13 int ERR_pop_to_mark(void);
14
15=head1 DESCRIPTION
16
17ERR_set_mark() sets a mark on the current topmost error record if there
18is one.
19
20ERR_pop_to_mark() will pop the top of the error stack until a mark is found.
21The mark is then removed. If there is no mark, the whole stack is removed.
22
23=head1 RETURN VALUES
24
25ERR_set_mark() returns 0 if the error stack is empty, otherwise 1.
26
27ERR_pop_to_mark() returns 0 if there was no mark in the error stack, which
28implies that the stack became empty, otherwise 1.
29
30=head1 SEE ALSO
31
32L<err(3)|err(3)>
33
34=head1 HISTORY
35
36ERR_set_mark() and ERR_pop_to_mark() were added in OpenSSL 0.9.8.
37
38=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 @@
1.Dd $Mdocdate: November 2 2016 $
2.Dt ERR 3
3.Os
4.Sh NAME
5.Nm ERR
6.Nd OpenSSL error codes
7.Sh SYNOPSIS
8.In openssl/err.h
9.Ft unsigned long
10.Fn ERR_get_error void
11.Ft unsigned long
12.Fn ERR_peek_error void
13.Ft unsigned long
14.Fo ERR_get_error_line
15.Fa "const char **file"
16.Fa "int *line"
17.Fc
18.Ft unsigned long
19.Fo ERR_peek_error_line
20.Fa "const char **file"
21.Fa "int *line"
22.Fc
23.Ft unsigned long
24.Fo ERR_get_error_line_data
25.Fa "const char **file"
26.Fa "int *line"
27.Fa "const char **data"
28.Fa "int *flags"
29.Fc
30.Ft unsigned long
31.Fo ERR_peek_error_line_data
32.Fa "const char **file"
33.Fa "int *line"
34.Fa "const char **data"
35.Fa "int *flags"
36.Fc
37.Ft int
38.Fo ERR_GET_LIB
39.Fa "unsigned long e"
40.Fc
41.Ft int
42.Fo ERR_GET_FUNC
43.Fa "unsigned long e"
44.Fc
45.Ft int
46.Fo ERR_GET_REASON
47.Fa "unsigned long e"
48.Fc
49.Ft void
50.Fn ERR_clear_error void
51.Ft char *
52.Fo ERR_error_string
53.Fa "unsigned long e"
54.Fa "char *buf"
55.Fc
56.Ft const char *
57.Fo ERR_lib_error_string
58.Fa "unsigned long e"
59.Fc
60.Ft const char *
61.Fo ERR_func_error_string
62.Fa "unsigned long e"
63.Fc
64.Ft const char *
65.Fo ERR_reason_error_string
66.Fa "unsigned long e"
67.Fc
68.Ft void
69.Fo ERR_print_errors
70.Fa "BIO *bp"
71.Fc
72.Ft void
73.Fo ERR_print_errors_fp
74.Fa "FILE *fp"
75.Fc
76.Ft void
77.Fn ERR_load_crypto_strings void
78.Ft void
79.Fn ERR_free_strings void
80.Ft void
81.Fo ERR_remove_state
82.Fa "unsigned long pid"
83.Fc
84.Ft void
85.Fo ERR_put_error
86.Fa "int lib"
87.Fa "int func"
88.Fa "int reason"
89.Fa "const char *file"
90.Fa "int line"
91.Fc
92.Ft void
93.Fo ERR_add_error_data
94.Fa "int num"
95.Fa ...
96.Fc
97.Ft void
98.Fo ERR_load_strings
99.Fa "int lib"
100.Fa "ERR_STRING_DATA str[]"
101.Fc
102.Ft unsigned long
103.Fo ERR_PACK
104.Fa "int lib"
105.Fa "int func"
106.Fa "int reason"
107.Fc
108.Ft int
109.Fn ERR_get_next_error_library void
110.Sh DESCRIPTION
111When a call to the OpenSSL library fails, this is usually signalled by
112the return value, and an error code is stored in an error queue
113associated with the current thread.
114The
115.Nm
116library provides functions to obtain these error codes and textual error
117messages.
118The
119.Xr ERR_get_error 3
120manpage describes how to access error codes.
121.Pp
122Error codes contain information about where the error occurred, and what
123went wrong.
124.Xr ERR_GET_LIB 3
125describes how to extract this information.
126A method to obtain human-readable error messages is described in
127.Xr ERR_error_string 3 .
128.Pp
129.Xr ERR_clear_error 3
130can be used to clear the error queue.
131.Pp
132Note that
133.Xr ERR_remove_state 3
134should be used to avoid memory leaks when threads are terminated.
135.Sh ADDING NEW ERROR CODES TO OPENSSL
136See
137.Xr ERR_put_error 3
138if you want to record error codes in the OpenSSL error system from
139within your application.
140.Pp
141The remainder of this section is of interest only if you want to add new
142error codes to OpenSSL or add error codes from external libraries.
143.Ss Reporting errors
144Each sub-library has a specific macro
145.Fn XXXerr f r
146that is used to report errors.
147Its first argument is a function code
148.Dv XXX_F_* ,
149the second argument is a reason code
150.Dv XXX_R_* .
151Function codes are derived from the function names; reason codes consist
152of textual error descriptions.
153For example, the function
154.Fn ssl23_read
155reports a "handshake failure" as follows:
156.Pp
157.Dl SSLerr(SSL_F_SSL23_READ, SSL_R_SSL_HANDSHAKE_FAILURE);
158.Pp
159Function and reason codes should consist of upper case characters,
160numbers and underscores only.
161The error file generation script translates function codes into function
162names by looking in the header files for an appropriate function name,
163if none is found it just uses the capitalized form such as "SSL23_READ"
164in the above example.
165.Pp
166The trailing section of a reason code (after the "_R_") is translated
167into lower case and underscores changed to spaces.
168.Pp
169When you are using new function or reason codes, run
170.Sy make errors .
171The necessary
172.Sy #define Ns s
173will then automatically be added to the sub-library's header file.
174.Pp
175Although a library will normally report errors using its own specific
176.Fn XXXerr
177macro, another library's macro can be used.
178This is normally only done when a library wants to include ASN1 code
179which must use the
180.Fn ASN1err
181macro.
182.Ss Adding new libraries
183When adding a new sub-library to OpenSSL, assign it a library number
184.Dv ERR_LIB_XXX ,
185define a macro
186.Fn XXXerr
187(both in
188.In openssl/err.h ) ,
189add its name to
190.Va ERR_str_libraries[]
191(in
192.Pa /usr/src/lib/libcrypto/err/err.c ) ,
193and add
194.Fn ERR_load_XXX_strings
195to the
196.Fn ERR_load_crypto_strings
197function (in
198.Sy /usr/src/lib/libcrypto/err/err_all.c ) .
199Finally, add an entry
200.Pp
201.Dl L XXX xxx.h xxx_err.c
202.Pp
203to
204.Sy /usr/src/lib/libcrypto/err/openssl.ec ,
205and add
206.Pa xxx_err.c
207to the
208.Pa Makefile .
209Running
210.Sy make errors
211will then generate a file
212.Pa xxx_err.c ,
213and add all error codes used in the library to
214.Pa xxx.h .
215.Pp
216Additionally the library include file must have a certain form.
217Typically it will initially look like this:
218.Bd -literal -offset indent
219#ifndef HEADER_XXX_H
220#define HEADER_XXX_H
221
222#ifdef __cplusplus
223extern "C" {
224#endif
225
226/* Include files */
227
228#include <openssl/bio.h>
229#include <openssl/x509.h>
230
231/* Macros, structures and function prototypes */
232
233/* BEGIN ERROR CODES */
234.Ed
235.Pp
236The
237.Sy BEGIN ERROR CODES
238sequence is used by the error code generation script as the point to
239place new error codes, any text after this point will be overwritten
240when
241.Sy make errors
242is run.
243The closing #endif etc. will be automatically added by the script.
244.Pp
245The generated C error code file
246.Pa xxx_err.c
247will load the header files
248.In stdio.h ,
249.In openssl/err.h
250and
251.In openssl/xxx.h
252so the header file must load any additional header files containing any
253definitions it uses.
254.Sh USING ERROR CODES IN EXTERNAL LIBRARIES
255It is also possible to use OpenSSL's error code scheme in external
256libraries.
257The library needs to load its own codes and call the OpenSSL error code
258insertion script
259.Pa mkerr.pl
260explicitly to add codes to the header file and generate the C error code
261file.
262This will normally be done if the external library needs to generate new
263ASN1 structures but it can also be used to add more general purpose
264error code handling.
265.Sh INTERNALS
266The error queues are stored in a hash table with one
267.Vt ERR_STATE
268entry for each pid.
269.Fn ERR_get_state
270returns the current thread's
271.Vt ERR_STATE .
272An
273.Vt ERR_STATE
274can hold up to
275.Dv ERR_NUM_ERRORS
276error codes.
277When more error codes are added, the old ones are overwritten, on the
278assumption that the most recent errors are most important.
279.Pp
280Error strings are also stored in hash table.
281The hash tables can be obtained by calling
282.Fn ERR_get_err_state_table
283and
284.Fn ERR_get_string_table .
285.Sh SEE ALSO
286.Xr CRYPTO_set_id_callback 3 ,
287.Xr CRYPTO_set_locking_callback 3 ,
288.Xr ERR_clear_error 3 ,
289.Xr ERR_error_string 3 ,
290.Xr ERR_get_error 3 ,
291.Xr ERR_GET_LIB 3 ,
292.Xr ERR_load_crypto_strings 3 ,
293.Xr ERR_load_strings 3 ,
294.Xr ERR_print_errors 3 ,
295.Xr ERR_put_error 3 ,
296.Xr ERR_remove_state 3 ,
297.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 @@
1.Dd $Mdocdate: November 2 2016 $
2.Dt ERR_GET_LIB 3
3.Os
4.Sh NAME
5.Nm ERR_GET_LIB ,
6.Nm ERR_GET_FUNC ,
7.Nm ERR_GET_REASON
8.Nd get library, function and reason codes for OpenSSL errors
9.Sh SYNOPSIS
10.In openssl/err.h
11.Ft int
12.Fo ERR_GET_LIB
13.Fa "unsigned long e"
14.Fc
15.Ft int
16.Fo ERR_GET_FUNC
17.Fa "unsigned long e"
18.Fc
19.Ft int
20.Fo ERR_GET_REASON
21.Fa "unsigned long e"
22.Fc
23.Sh DESCRIPTION
24The error code returned by
25.Xr ERR_get_error 3
26consists of a library number, function code, and reason code.
27.Fn ERR_GET_LIB ,
28.Fn ERR_GET_FUNC ,
29and
30.Fn ERR_GET_REASON
31can be used to extract these.
32.Pp
33The library number and function code describe where the error occurred,
34the reason code is the information about what went wrong.
35.Pp
36Each sub-library of OpenSSL has a unique library number; function and
37reason codes are unique within each sub-library.
38Note that different libraries may use the same value to signal different
39functions and reasons.
40.Pp
41.Dv ERR_R_*
42reason codes such as
43.Dv ERR_R_MALLOC_FAILURE
44are globally unique.
45However, when checking for sub-library specific reason codes, be sure to
46also compare the library number.
47.Pp
48.Fn ERR_GET_LIB ,
49.Fn ERR_GET_FUNC ,
50and
51.Fn ERR_GET_REASON
52are macros.
53.Sh RETURN VALUES
54The library number, function code, and reason code, respectively.
55.Sh SEE ALSO
56.Xr ERR 3 ,
57.Xr ERR_get_error 3
58.Sh HISTORY
59.Fn ERR_GET_LIB ,
60.Fn ERR_GET_FUNC ,
61and
62.Fn ERR_GET_REASON
63are 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 @@
1.Dd $Mdocdate: November 2 2016 $
2.Dt ERR_CLEAR_ERROR 3
3.Os
4.Sh NAME
5.Nm ERR_clear_error
6.Nd clear the OpenSSL error queue
7.Sh SYNOPSIS
8.In openssl/err.h
9.Ft void
10.Fn ERR_clear_error void
11.Sh DESCRIPTION
12.Fn ERR_clear_error
13empties the current thread's error queue.
14.Sh RETURN VALUES
15.Fn ERR_clear_error
16has no return value.
17.Sh SEE ALSO
18.Xr ERR 3 ,
19.Xr ERR_get_error 3
20.Sh HISTORY
21.Fn ERR_clear_error
22is 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 @@
1.Dd $Mdocdate: November 2 2016 $
2.Dt ERR_ERROR_STRING 3
3.Os
4.Sh NAME
5.Nm ERR_error_string ,
6.Nm ERR_error_string_n ,
7.Nm ERR_lib_error_string ,
8.Nm ERR_func_error_string ,
9.Nm ERR_reason_error_string
10.Nd obtain human-readable OpenSSL error messages
11.Sh SYNOPSIS
12.In openssl/err.h
13.Ft char *
14.Fo ERR_error_string
15.Fa "unsigned long e"
16.Fa "char *buf"
17.Fc
18.Ft void
19.Fo ERR_error_string_n
20.Fa "unsigned long e"
21.Fa "char *buf"
22.Fa "size_t len"
23.Fc
24.Ft const char *
25.Fo ERR_lib_error_string
26.Fa "unsigned long e"
27.Fc
28.Ft const char *
29.Fo ERR_func_error_string
30.Fa "unsigned long e"
31.Fc
32.Ft const char *
33.Fo ERR_reason_error_string
34.Fa "unsigned long e"
35.Fc
36.Sh DESCRIPTION
37.Fn ERR_error_string
38generates a human-readable string representing the error code
39.Fa e
40and places it in
41.Fa buf .
42.Fa buf
43must be at least 120 bytes long.
44If
45.Fa buf
46is
47.Dv NULL ,
48the error string is placed in a static buffer.
49.Fn ERR_error_string_n
50is a variant of
51.Fn ERR_error_string
52that writes at most
53.Fa len
54characters (including the terminating NUL) and truncates the string
55if necessary.
56For
57.Fn ERR_error_string_n ,
58.Fa buf
59may not be
60.Dv NULL .
61.Pp
62The string will have the following format:
63.Pp
64.Dl error:[error code]:[library name]:[function name]:[reason string]
65.Pp
66The error code is an 8 digit hexadecimal number.
67The library name, the function name, and the reason string are ASCII
68text.
69.Pp
70.Fn ERR_lib_error_string ,
71.Fn ERR_func_error_string ,
72and
73.Fn ERR_reason_error_string
74return the library name, the function name, and the reason string,
75respectively.
76.Pp
77The OpenSSL error strings should be loaded by calling
78.Xr ERR_load_crypto_strings 3
79or, for SSL applications,
80.Xr SSL_load_error_strings 3
81first.
82If there is no text string registered for the given error code, the
83error string will contain the numeric code.
84.Pp
85.Xr ERR_print_errors 3
86can be used to print all error codes currently in the queue.
87.Sh RETURN VALUES
88.Fn ERR_error_string
89returns a pointer to a static buffer containing the string if
90.Fa buf
91is
92.Dv NULL ,
93or
94.Fa buf
95otherwise.
96.Pp
97.Fn ERR_lib_error_string ,
98.Fn ERR_func_error_string ,
99and
100.Fn ERR_reason_error_string
101return the strings, or
102.Dv NULL
103if none is registered for the error code.
104.Sh SEE ALSO
105.Xr ERR 3 ,
106.Xr ERR_get_error 3 ,
107.Xr ERR_load_crypto_strings 3 ,
108.Xr ERR_print_errors 3 ,
109.Xr SSL_load_error_strings 3
110.Sh HISTORY
111.Fn ERR_error_string
112is available in all versions of SSLeay and OpenSSL.
113.Fn ERR_error_string_n
114was 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 @@
1.Dd $Mdocdate: November 2 2016 $
2.Dt ERR_GET_ERROR 3
3.Os
4.Sh NAME
5.Nm ERR_get_error ,
6.Nm ERR_peek_error ,
7.Nm ERR_peek_last_error ,
8.Nm ERR_get_error_line ,
9.Nm ERR_peek_error_line ,
10.Nm ERR_peek_last_error_line ,
11.Nm ERR_get_error_line_data ,
12.Nm ERR_peek_error_line_data ,
13.Nm ERR_peek_last_error_line_data
14.Nd obtain OpenSSL error code and data
15.Sh SYNOPSIS
16.In openssl/err.h
17.Ft unsigned long
18.Fn ERR_get_error void
19.Ft unsigned long
20.Fn ERR_peek_error void
21.Ft unsigned long
22.Fn ERR_peek_last_error void
23.Ft unsigned long
24.Fo ERR_get_error_line
25.Fa "const char **file"
26.Fa "int *line"
27.Fc
28.Ft unsigned long
29.Fo ERR_peek_error_line
30.Fa "const char **file"
31.Fa "int *line"
32.Fc
33.Ft unsigned long
34.Fo ERR_peek_last_error_line
35.Fa "const char **file"
36.Fa "int *line"
37.Fc
38.Ft unsigned long
39.Fo ERR_get_error_line_data
40.Fa "const char **file"
41.Fa "int *line"
42.Fa "const char **data"
43.Fa "int *flags"
44.Fc
45.Ft unsigned long
46.Fo ERR_peek_error_line_data
47.Fa "const char **file"
48.Fa "int *line"
49.Fa "const char **data"
50.Fa "int *flags"
51.Fc
52.Ft unsigned long
53.Fo ERR_peek_last_error_line_data
54.Fa "const char **file"
55.Fa "int *line"
56.Fa "const char **data"
57.Fa "int *flags"
58.Fc
59.Sh DESCRIPTION
60.Fn ERR_get_error
61returns the earliest error code from the thread's error queue and
62removes the entry.
63This function can be called repeatedly until there are no more error
64codes to return.
65.Pp
66.Fn ERR_peek_error
67returns the earliest error code from the thread's error queue without
68modifying it.
69.Pp
70.Fn ERR_peek_last_error
71returns the latest error code from the thread's error queue without
72modifying it.
73.Pp
74See
75.Xr ERR_GET_LIB 3
76for obtaining information about location and reason of the error, and
77.Xr ERR_error_string 3
78for human-readable error messages.
79.Pp
80.Fn ERR_get_error_line ,
81.Fn ERR_peek_error_line ,
82and
83.Fn ERR_peek_last_error_line
84are the same as the above, but they additionally store the file name and
85line number where the error occurred in
86.Pf * Fa file
87and
88.Pf * Fa line ,
89unless these are
90.Dv NULL .
91.Pp
92.Fn ERR_get_error_line_data ,
93.Fn ERR_peek_error_line_data ,
94and
95.Fn ERR_peek_last_error_line_data
96store additional data and flags associated with the error code in
97.Pf * Fa data
98and
99.Pf * Fa flags ,
100unless these are
101.Dv NULL .
102.Pf * Fa data
103contains a string if
104.Pf * Fa flags Ns & Ns Dv ERR_TXT_STRING
105is true.
106.Pp
107An application
108.Sy MUST NOT
109free the
110.Pf * Fa data
111pointer (or any other pointers returned by these functions) with
112.Xr free 3
113as freeing is handled automatically by the error library.
114.Sh RETURN VALUES
115The error code, or 0 if there is no error in the queue.
116.Sh SEE ALSO
117.Xr ERR 3 ,
118.Xr ERR_error_string 3 ,
119.Xr ERR_GET_LIB 3
120.Sh HISTORY
121.Fn ERR_get_error ,
122.Fn ERR_peek_error ,
123.Fn ERR_get_error_line ,
124and
125.Fn ERR_peek_error_line
126are available in all versions of SSLeay and OpenSSL.
127.Fn ERR_get_error_line_data
128and
129.Fn ERR_peek_error_line_data
130were added in SSLeay 0.9.0.
131.Fn ERR_peek_last_error ,
132.Fn ERR_peek_last_error_line ,
133and
134.Fn ERR_peek_last_error_line_data
135were 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 @@
1.Dd $Mdocdate: November 2 2016 $
2.Dt ERR_LOAD_CRYPTO_STRINGS 3
3.Os
4.Sh NAME
5.Nm ERR_load_crypto_strings ,
6.Nm SSL_load_error_strings ,
7.Nm ERR_free_strings
8.Nd load and free OpenSSL error strings
9.Sh SYNOPSIS
10.In openssl/err.h
11.Ft void
12.Fn ERR_load_crypto_strings void
13.Ft void
14.Fn ERR_free_strings void
15.In openssl/ssl.h
16.Ft void
17.Fn SSL_load_error_strings void
18.Sh DESCRIPTION
19.Fn ERR_load_crypto_strings
20registers the error strings for all
21.Xr crypto 3
22functions.
23.Fn SSL_load_error_strings
24does the same, but also registers the
25.Xr ssl 3
26error strings.
27.Pp
28One of these functions should be called before generating textual error
29messages.
30However, this is not required when memory usage is an issue.
31.Pp
32.Fn ERR_free_strings
33frees all previously loaded error strings.
34.Sh RETURN VALUES
35.Fn ERR_load_crypto_strings ,
36.Fn SSL_load_error_strings ,
37and
38.Fn ERR_free_strings
39return no values.
40.Sh SEE ALSO
41.Xr ERR 3 ,
42.Xr ERR_error_string 3
43.Sh HISTORY
44.Xr ERR_load_error_strings 3 ,
45.Fn SSL_load_error_strings ,
46and
47.Fn ERR_free_strings
48are 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 @@
1.Dd $Mdocdate: November 2 2016 $
2.Dt ERR_LOAD_STRINGS 3
3.Os
4.Sh NAME
5.Nm ERR_load_strings ,
6.Nm ERR_PACK ,
7.Nm ERR_get_next_error_library
8.Nd load arbitrary OpenSSL error strings
9.Sh SYNOPSIS
10.In openssl/err.h
11.Ft void
12.Fo ERR_load_strings
13.Fa "int lib"
14.Fa "ERR_STRING_DATA str[]"
15.Fc
16.Ft int
17.Fn ERR_get_next_error_library void
18.Ft unsigned long
19.Fo ERR_PACK
20.Fa "int lib"
21.Fa "int func"
22.Fa "int reason"
23.Fc
24.Sh DESCRIPTION
25.Fn ERR_load_strings
26registers error strings for library number
27.Fa lib .
28.Pp
29.Fa str
30is an array of error string data:
31.Bd -literal -offset indent
32typedef struct ERR_string_data_st
33{
34 unsigned long error;
35 char *string;
36} ERR_STRING_DATA;
37.Ed
38.Pp
39The error code is generated from the library number and a function and
40reason code:
41.Pp
42.Dl error = ERR_PACK(lib, func, reason)
43.Pp
44.Fn ERR_PACK
45is a macro.
46.Pp
47The last entry in the array is
48.Brq 0 , Dv NULL .
49.Pp
50.Fn ERR_get_next_error_library
51can be used to assign library numbers to user libraries at runtime.
52.Sh RETURN VALUE
53.Fn ERR_PACK
54returns the error code.
55.Fn ERR_get_next_error_library
56returns a new library number.
57.Sh SEE ALSO
58.Xr ERR 3 ,
59.Xr ERR_load_strings 3
60.Sh HISTORY
61.Xr ERR_load_error_strings 3
62and
63.Fn ERR_PACK
64are available in all versions of SSLeay and OpenSSL.
65.Fn ERR_get_next_error_library
66was 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 @@
1.Dd $Mdocdate: November 2 2016 $
2.Dt ERR_PRINT_ERRORS 3
3.Os
4.Sh NAME
5.Nm ERR_print_errors ,
6.Nm ERR_print_errors_fp
7.Nd print OpenSSL error messages
8.Sh SYNOPSIS
9.In openssl/err.h
10.Ft void
11.Fo ERR_print_errors
12.Fa "BIO *bp"
13.Fc
14.Ft void
15.Fo ERR_print_errors_fp
16.Fa "FILE *fp"
17.Fc
18.Sh DESCRIPTION
19.Fn ERR_print_errors
20is a convenience function that prints the error strings for all errors
21that OpenSSL has recorded to
22.Fa bp ,
23thus emptying the error queue.
24.Pp
25.Fn ERR_print_errors_fp
26is the same, except that the output goes to a
27.Vt FILE .
28.Pp
29The error strings have the following format:
30.Bd -literal
31[pid]:error:[error code]:[library name]:[function name]:[reason string]:
32[file name]:[line]:[optional text message]
33.Ed
34.Pp
35The error code is an 8 digit hexadecimal number.
36The library name, the function name, and the reason string are ASCII
37text, as is the optional text message if one was set for the
38respective error code.
39.Pp
40If there is no text string registered for the given error code, the
41error string will contain the numeric code.
42.Sh RETURN VALUES
43.Fn ERR_print_errors
44and
45.Fn ERR_print_errors_fp
46return no values.
47.Sh SEE ALSO
48.Xr ERR 3 ,
49.Xr ERR_error_string 3 ,
50.Xr ERR_get_error 3 ,
51.Xr ERR_load_crypto_strings 3 ,
52.Xr SSL_load_error_strings 3
53.Sh HISTORY
54.Fn ERR_print_errors
55and
56.Fn ERR_print_errors_fp
57are 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 @@
1.Dd $Mdocdate: November 2 2016 $
2.Dt ERR_PUT_ERROR 3
3.Os
4.Sh NAME
5.Nm ERR_put_error ,
6.Nm ERR_add_error_data
7.Nd record an OpenSSL error
8.Sh SYNOPSIS
9.In openssl/err.h
10.Ft void
11.Fo ERR_put_error
12.Fa "int lib"
13.Fa "int func"
14.Fa "int reason"
15.Fa "const char *file"
16.Fa "int line"
17.Fc
18.Ft void
19.Fo ERR_add_error_data
20.Fa "int num"
21.Fa ...
22.Fc
23.Sh DESCRIPTION
24.Fn ERR_put_error
25adds an error code to the thread's error queue.
26It signals that the error of reason code
27.Fa reason
28occurred in function
29.Fa func
30of library
31.Fa lib ,
32in line number
33.Fa line
34of
35.Fa file .
36This function is usually called by a macro.
37.Pp
38.Fn ERR_add_error_data
39associates the concatenation of its
40.Fa num
41string arguments with the error code added last.
42.Pp
43.Xr ERR_load_strings 3
44can be used to register error strings so that the application can a
45generate human-readable error messages for the error code.
46.Sh RETURN VALUES
47.Fn ERR_put_error
48and
49.Fn ERR_add_error_data
50return no values.
51.Sh SEE ALSO
52.Xr ERR 3 ,
53.Xr ERR_load_strings 3
54.Sh HISTORY
55.Fn ERR_put_error
56is available in all versions of SSLeay and OpenSSL.
57.Fn ERR_add_error_data
58was 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 @@
1.Dd $Mdocdate: November 2 2016 $
2.Dt ERR_REMOVE_STATE 3
3.Os
4.Sh NAME
5.Nm ERR_remove_thread_state ,
6.Nm ERR_remove_state
7.Nd free a thread's OpenSSL error queue
8.Sh SYNOPSIS
9.In openssl/err.h
10.Ft void
11.Fo ERR_remove_thread_state
12.Fa "const CRYPTO_THREADID *tid"
13.Fc
14.Pp
15Deprecated:
16.Pp
17.Ft void
18.Fo ERR_remove_state
19.Fa "unsigned long pid"
20.Fc
21.Sh DESCRIPTION
22.Fn ERR_remove_thread_state
23frees the error queue associated with thread
24.Fa tid .
25If
26.Fa tid
27is
28.Dv NULL ,
29the current thread will have its error queue removed.
30.Pp
31Since error queue data structures are allocated automatically for new
32threads, they must be freed when threads are terminated in order to
33avoid memory leaks.
34.Pp
35.Fn ERR_remove_state
36is deprecated and has been replaced by
37.Fn ERR_remove_thread_state .
38Since threads in OpenSSL are no longer identified by unsigned long
39values, any argument to this function is ignored.
40Calling
41.Fn ERR_remove_state
42is equivalent to
43.Fn ERR_remove_thread_state NULL .
44.Sh RETURN VALUE
45.Fn ERR_remove_thread_state
46and
47.Fn ERR_remove_state
48return no value.
49.Sh SEE ALSO
50.Xr ERR 3
51.Sh HISTORY
52.Fn ERR_remove_state
53is available in all versions of SSLeay and OpenSSL.
54It was deprecated in OpenSSL 1.0.0 when
55.Fn ERR_remove_thread_state
56was introduced and thread IDs were introduced to identify threads
57instead of
58.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 @@
1.Dd $Mdocdate: November 2 2016 $
2.Dt ERR_SET_MARK 3
3.Os
4.Sh NAME
5.Nm ERR_set_mark ,
6.Nm ERR_pop_to_mark
7.Nd set marks and pop OpenSSL errors until mark
8.Sh SYNOPSIS
9.In openssl/err.h
10.Ft int
11.Fn ERR_set_mark void
12.Ft int
13.Fn ERR_pop_to_mark void
14.Sh DESCRIPTION
15.Fn ERR_set_mark
16sets a mark on the current topmost error record if there is one.
17.Pp
18.Fn ERR_pop_to_mark
19will pop the top of the error stack until a mark is found.
20The mark is then removed.
21If there is no mark, the whole stack is removed.
22.Sh RETURN VALUES
23.Fn ERR_set_mark
24returns 0 if the error stack is empty, otherwise 1.
25.Pp
26.Fn ERR_pop_to_mark
27returns 0 if there was no mark in the error stack, which implies that
28the stack became empty, otherwise 1.
29.Sh SEE ALSO
30.Xr ERR 3
31.Sh HISTORY
32.Fn ERR_set_mark
33and
34.Fn ERR_pop_to_mark
35were 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 @@
1# $OpenBSD: Makefile,v 1.36 2016/11/02 11:57:56 schwarze Exp $ 1# $OpenBSD: Makefile,v 1.37 2016/11/02 15:23:41 schwarze Exp $
2 2
3.include <bsd.own.mk> # for NOMAN 3.include <bsd.own.mk> # for NOMAN
4 4
@@ -80,15 +80,6 @@ MAN= \
80 EC_POINT_add.3 \ 80 EC_POINT_add.3 \
81 EC_POINT_new.3 \ 81 EC_POINT_new.3 \
82 ECDSA_SIG_new.3 \ 82 ECDSA_SIG_new.3 \
83 EVP_AEAD_CTX_init.3 \
84 UI_new.3 \
85 bn_dump.3 \
86 crypto.3 \
87 d2i_PKCS8PrivateKey_bio.3 \
88 des_read_pw.3 \
89 lh_new.3 \
90
91GENMAN= \
92 ERR.3 \ 83 ERR.3 \
93 ERR_GET_LIB.3 \ 84 ERR_GET_LIB.3 \
94 ERR_clear_error.3 \ 85 ERR_clear_error.3 \
@@ -100,6 +91,15 @@ GENMAN= \
100 ERR_put_error.3 \ 91 ERR_put_error.3 \
101 ERR_remove_state.3 \ 92 ERR_remove_state.3 \
102 ERR_set_mark.3 \ 93 ERR_set_mark.3 \
94 EVP_AEAD_CTX_init.3 \
95 UI_new.3 \
96 bn_dump.3 \
97 crypto.3 \
98 d2i_PKCS8PrivateKey_bio.3 \
99 des_read_pw.3 \
100 lh_new.3 \
101
102GENMAN= \
103 EVP_BytesToKey.3 \ 103 EVP_BytesToKey.3 \
104 EVP_DigestInit.3 \ 104 EVP_DigestInit.3 \
105 EVP_DigestSignInit.3 \ 105 EVP_DigestSignInit.3 \
generated by cgit v1.2.3-55-g6feb (git 2.39.1) at 2025-12-09 14:43:49 +0000