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