]>
Commit | Line | Data |
---|---|---|
388f2f56 UM |
1 | =pod |
2 | ||
2b93900e RL |
3 | =for openssl foreign manual errno(3) |
4 | ||
388f2f56 UM |
5 | =head1 NAME |
6 | ||
ed57f7f9 | 7 | ERR_raise, ERR_raise_data, |
31b28ad9 DDO |
8 | ERR_put_error, ERR_add_error_data, ERR_add_error_vdata, |
9 | ERR_add_error_txt, ERR_add_error_mem_bio | |
add8c8e9 | 10 | - record an error |
388f2f56 UM |
11 | |
12 | =head1 SYNOPSIS | |
13 | ||
14 | #include <openssl/err.h> | |
15 | ||
ed57f7f9 RL |
16 | void ERR_raise(int lib, int reason); |
17 | void ERR_raise_data(int lib, int reason, const char *fmt, ...); | |
18 | ||
388f2f56 | 19 | void ERR_add_error_data(int num, ...); |
61ced34f | 20 | void ERR_add_error_vdata(int num, va_list arg); |
31b28ad9 DDO |
21 | void ERR_add_error_txt(const char *sep, const char *txt); |
22 | void ERR_add_error_mem_bio(const char *sep, BIO *bio); | |
388f2f56 | 23 | |
3dbf8243 MC |
24 | The following function has been deprecated since OpenSSL 3.0, and can be |
25 | hidden entirely by defining B<OPENSSL_API_COMPAT> with a suitable version value, | |
26 | see L<openssl_user_macros(7)>: | |
add8c8e9 RL |
27 | |
28 | void ERR_put_error(int lib, int func, int reason, const char *file, int line); | |
29 | ||
388f2f56 UM |
30 | =head1 DESCRIPTION |
31 | ||
ed57f7f9 | 32 | ERR_raise() adds a new error to the thread's error queue. The |
79c44b4e | 33 | error occurred in the library B<lib> for the reason given by the |
ed57f7f9 | 34 | B<reason> code. Furthermore, the name of the file, the line, and name |
79c44b4e | 35 | of the function where the error occurred is saved with the error |
ed57f7f9 RL |
36 | record. |
37 | ||
38 | ERR_raise_data() does the same thing as ERR_raise(), but also lets the | |
39 | caller specify additional information as a format string B<fmt> and an | |
57cd10dd | 40 | arbitrary number of values, which are processed with L<BIO_snprintf(3)>. |
ed57f7f9 | 41 | |
388f2f56 UM |
42 | ERR_put_error() adds an error code to the thread's error queue. It |
43 | signals that the error of reason code B<reason> occurred in function | |
44 | B<func> of library B<lib>, in line number B<line> of B<file>. | |
45 | This function is usually called by a macro. | |
46 | ||
47 | ERR_add_error_data() associates the concatenation of its B<num> string | |
31b28ad9 | 48 | arguments as additional data with the error code added last. |
c952780c | 49 | ERR_add_error_vdata() is similar except the argument is a B<va_list>. |
8908d18c | 50 | Multiple calls to these functions append to the current top of the error queue. |
31b28ad9 DDO |
51 | The total length of the string data per error is limited to 4096 characters. |
52 | ||
53 | ERR_add_error_txt() appends the given text string as additional data to the | |
54 | last error queue entry, after inserting the optional separator string if it is | |
55 | not NULL and the top error entry does not yet have additional data. | |
56 | In case the separator is at the end of the text it is not appended to the data. | |
57 | The B<sep> argument may be for instance "\n" to insert a line break when needed. | |
58 | If the associated data would become more than 4096 characters long | |
59 | (which is the limit given above) | |
60 | it is split over sufficiently many new copies of the last error queue entry. | |
61 | ||
62 | ERR_add_error_mem_bio() is the same as ERR_add_error_txt() except that | |
63 | the text string is taken from the given memory BIO. | |
64 | It appends '\0' to the BIO contents if not already NUL-terminated. | |
388f2f56 | 65 | |
9b86974e | 66 | L<ERR_load_strings(3)> can be used to register |
388f2f56 UM |
67 | error strings so that the application can a generate human-readable |
68 | error messages for the error code. | |
69 | ||
53934822 RS |
70 | =head2 Reporting errors |
71 | ||
2b93900e RL |
72 | =head3 OpenSSL library reports |
73 | ||
74 | Each OpenSSL sub-library has library code B<ERR_LIB_XXX> and has its own set | |
75 | of reason codes B<XXX_R_...>. These are both passed in combination to | |
76 | ERR_raise() and ERR_raise_data(), and the combination ultimately produces | |
77 | the correct error text for the reported error. | |
add8c8e9 | 78 | |
2b93900e RL |
79 | All these macros and the numbers they have as values are specific to |
80 | OpenSSL's libraries. OpenSSL reason codes normally consist of textual error | |
53934822 RS |
81 | descriptions. For example, the function ssl3_read_bytes() reports a |
82 | "handshake failure" as follows: | |
83 | ||
2b93900e RL |
84 | ERR_raise(ERR_LIB_SSL, SSL_R_SSL_HANDSHAKE_FAILURE); |
85 | ||
86 | There are two exceptions: | |
87 | ||
88 | =over 4 | |
89 | ||
90 | =item B<ERR_LIB_SYS> | |
91 | ||
92 | This "library code" indicates that a system error is being reported. In | |
93 | this case, the reason code given to ERR_raise() and ERR_raise_data() I<must> | |
94 | be L<errno(3)>. | |
95 | ||
96 | ERR_raise(ERR_LIB_SYS, errno); | |
97 | ||
98 | =item B<ERR_R_XXX> | |
99 | ||
100 | This set of error codes is considered global, and may be used in combination | |
101 | with any sub-library code. | |
102 | ||
103 | ERR_raise(ERR_LIB_RSA, ERR_R_PASSED_INVALID_ARGUMENT); | |
104 | ||
105 | =back | |
106 | ||
107 | =head3 Other pieces of software | |
108 | ||
109 | Other pieces of software that may want to use OpenSSL's error reporting | |
110 | system, such as engines or applications, must normally get their own | |
111 | numbers. | |
112 | ||
113 | =over 4 | |
114 | ||
115 | =item * | |
116 | ||
117 | To get a "library" code, call L<ERR_get_next_error_library(3)>; this gives | |
118 | the calling code a dynamic number, usable for the duration of the process. | |
119 | ||
120 | =item * | |
121 | ||
122 | Reason codes for each such "library" are determined or generated by the | |
123 | authors of that code. They must be numbers in the range 1 to 524287 (in | |
124 | other words, they must be nonzero unsigned 18 bit integers). | |
125 | ||
126 | =back | |
127 | ||
128 | The exceptions mentioned in L</OpenSSL library reports> above are valid for | |
129 | other pieces of software, i.e. they may use B<ERR_LIB_SYS> to report system | |
130 | errors: | |
131 | ||
132 | ERR_raise(ERR_LIB_SYS, errno); | |
133 | ||
134 | ... and they may use B<ERR_R_XXX> macros together with their own "library" | |
135 | code. | |
136 | ||
137 | int app_lib_code = ERR_get_next_error_library(); | |
138 | ||
139 | /* ... */ | |
140 | ||
141 | ERR_raise(app_lib_code, ERR_R_PASSED_INVALID_ARGUMENT); | |
142 | ||
143 | =begin comment | |
53934822 | 144 | |
2b93900e | 145 | [These are OpenSSL specific recommendations] |
53934822 | 146 | |
2b93900e RL |
147 | Reason codes should consist of uppercase characters, numbers and underscores |
148 | only. The error file generation script translates the trailing section of a | |
149 | reason code (after the "_R_") into lowercase with underscores changed to | |
150 | spaces. | |
53934822 | 151 | |
53934822 | 152 | Although a library will normally report errors using its own specific |
2b93900e RL |
153 | B<ERR_LIB_XXX> macro, another library's macro can be used, together with |
154 | that other library's reason codes. This is normally only done when a library | |
155 | wants to include ASN1 code which must be combined with B<ERR_LIB_ASN1> | |
156 | macro. | |
53934822 | 157 | |
2b93900e | 158 | =end comment |
53934822 | 159 | |
388f2f56 UM |
160 | =head1 RETURN VALUES |
161 | ||
2b93900e | 162 | ERR_raise(), ERR_raise_data(), ERR_put_error(), |
31b28ad9 DDO |
163 | ERR_add_error_data(), ERR_add_error_vdata() |
164 | ERR_add_error_txt(), and ERR_add_error_mem_bio() | |
165 | return no values. | |
ed57f7f9 RL |
166 | |
167 | =head1 NOTES | |
168 | ||
2b93900e | 169 | ERR_raise(), ERR_raise() and ERR_put_error() are implemented as macros. |
388f2f56 UM |
170 | |
171 | =head1 SEE ALSO | |
172 | ||
2b93900e | 173 | L<ERR_load_strings(3)>, L<ERR_get_next_error_library(3)> |
388f2f56 | 174 | |
31b28ad9 DDO |
175 | =head1 HISTORY |
176 | ||
2b93900e RL |
177 | ERR_raise, ERR_raise_data, ERR_add_error_txt() and ERR_add_error_mem_bio() |
178 | were added in OpenSSL 3.0. | |
31b28ad9 | 179 | |
e2f92610 RS |
180 | =head1 COPYRIGHT |
181 | ||
33388b44 | 182 | Copyright 2000-2020 The OpenSSL Project Authors. All Rights Reserved. |
e2f92610 | 183 | |
4746f25a | 184 | Licensed under the Apache License 2.0 (the "License"). You may not use |
e2f92610 RS |
185 | this file except in compliance with the License. You can obtain a copy |
186 | in the file LICENSE in the source distribution or at | |
187 | L<https://www.openssl.org/source/license.html>. | |
188 | ||
189 | =cut |