]>
Commit | Line | Data |
---|---|---|
388f2f56 UM |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
4d524e10 | 5 | err - error codes |
388f2f56 UM |
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); | |
388f2f56 | 35 | |
388f2f56 UM |
36 | void ERR_put_error(int lib, int func, int reason, const char *file, |
37 | int line); | |
38 | void ERR_add_error_data(int num, ...); | |
39 | ||
40 | void ERR_load_strings(int lib,ERR_STRING_DATA str[]); | |
41 | unsigned long ERR_PACK(int lib, int func, int reason); | |
42 | int ERR_get_next_error_library(void); | |
43 | ||
98186eb4 VD |
44 | Deprecated: |
45 | ||
46 | #if OPENSSL_API_COMPAT < 0x10000000L | |
47 | void ERR_remove_state(unsigned long pid); | |
48 | #endif | |
49 | ||
21e00174 RL |
50 | #if OPENSSL_API_COMPAT < 0x10100000L |
51 | void ERR_remove_thread_state(void *); | |
52 | #endif | |
53 | ||
6827cb36 | 54 | #if OPENSSL_API_COMPAT < 0x10100000L |
1d5099de | 55 | void ERR_free_strings(void) |
6827cb36 MC |
56 | #endif |
57 | ||
58 | ||
388f2f56 UM |
59 | =head1 DESCRIPTION |
60 | ||
186bb907 | 61 | When a call to the OpenSSL library fails, this is usually signaled |
388f2f56 UM |
62 | by the return value, and an error code is stored in an error queue |
63 | associated with the current thread. The B<err> library provides | |
64 | functions to obtain these error codes and textual error messages. | |
65 | ||
9b86974e | 66 | The L<ERR_get_error(3)> manpage describes how to |
388f2f56 UM |
67 | access error codes. |
68 | ||
69 | Error codes contain information about where the error occurred, and | |
9b86974e | 70 | what went wrong. L<ERR_GET_LIB(3)> describes how to |
388f2f56 | 71 | extract this information. A method to obtain human-readable error |
9b86974e | 72 | messages is described in L<ERR_error_string(3)>. |
388f2f56 | 73 | |
9b86974e | 74 | L<ERR_clear_error(3)> can be used to clear the |
388f2f56 UM |
75 | error queue. |
76 | ||
388f2f56 UM |
77 | =head1 ADDING NEW ERROR CODES TO OPENSSL |
78 | ||
79 | See L<ERR_put_error(3)> if you want to record error codes in the | |
80 | OpenSSL error system from within your application. | |
81 | ||
82 | The remainder of this section is of interest only if you want to add | |
54a34aec | 83 | new error codes to OpenSSL or add error codes from external libraries. |
388f2f56 UM |
84 | |
85 | =head2 Reporting errors | |
86 | ||
87 | Each sub-library has a specific macro XXXerr() that is used to report | |
88 | errors. Its first argument is a function code B<XXX_F_...>, the second | |
89 | argument is a reason code B<XXX_R_...>. Function codes are derived | |
90 | from the function names; reason codes consist of textual error | |
a27e81ee | 91 | descriptions. For example, the function ssl3_read_bytes() reports a |
388f2f56 UM |
92 | "handshake failure" as follows: |
93 | ||
a27e81ee | 94 | SSLerr(SSL_F_SSL3_READ_BYTES, SSL_R_SSL_HANDSHAKE_FAILURE); |
388f2f56 | 95 | |
82fc1d9c DSH |
96 | Function and reason codes should consist of upper case characters, |
97 | numbers and underscores only. The error file generation script translates | |
98 | function codes into function names by looking in the header files | |
99 | for an appropriate function name, if none is found it just uses | |
a27e81ee | 100 | the capitalized form such as "SSL3_READ_BYTES" in the above example. |
82fc1d9c DSH |
101 | |
102 | The trailing section of a reason code (after the "_R_") is translated | |
9dbc41d7 | 103 | into lower case and underscores changed to spaces. |
82fc1d9c | 104 | |
388f2f56 UM |
105 | When you are using new function or reason codes, run B<make errors>. |
106 | The necessary B<#define>s will then automatically be added to the | |
107 | sub-library's header file. | |
108 | ||
54a34aec | 109 | Although a library will normally report errors using its own specific |
82fc1d9c DSH |
110 | XXXerr macro, another library's macro can be used. This is normally |
111 | only done when a library wants to include ASN1 code which must use | |
112 | the ASN1err() macro. | |
54a34aec | 113 | |
388f2f56 UM |
114 | =head2 Adding new libraries |
115 | ||
116 | When adding a new sub-library to OpenSSL, assign it a library number | |
117 | B<ERR_LIB_XXX>, define a macro XXXerr() (both in B<err.h>), add its | |
118 | name to B<ERR_str_libraries[]> (in B<crypto/err/err.c>), and add | |
119 | C<ERR_load_XXX_strings()> to the ERR_load_crypto_strings() function | |
120 | (in B<crypto/err/err_all.c>). Finally, add an entry | |
121 | ||
1bc74519 | 122 | L XXX xxx.h xxx_err.c |
388f2f56 UM |
123 | |
124 | to B<crypto/err/openssl.ec>, and add B<xxx_err.c> to the Makefile. | |
125 | Running B<make errors> will then generate a file B<xxx_err.c>, and | |
126 | add all error codes used in the library to B<xxx.h>. | |
127 | ||
54a34aec DSH |
128 | Additionally the library include file must have a certain form. |
129 | Typically it will initially look like this: | |
130 | ||
131 | #ifndef HEADER_XXX_H | |
132 | #define HEADER_XXX_H | |
133 | ||
134 | #ifdef __cplusplus | |
135 | extern "C" { | |
136 | #endif | |
137 | ||
138 | /* Include files */ | |
139 | ||
140 | #include <openssl/bio.h> | |
141 | #include <openssl/x509.h> | |
142 | ||
143 | /* Macros, structures and function prototypes */ | |
144 | ||
145 | ||
146 | /* BEGIN ERROR CODES */ | |
147 | ||
148 | The B<BEGIN ERROR CODES> sequence is used by the error code | |
149 | generation script as the point to place new error codes, any text | |
150 | after this point will be overwritten when B<make errors> is run. | |
151 | The closing #endif etc will be automatically added by the script. | |
152 | ||
153 | The generated C error code file B<xxx_err.c> will load the header | |
154 | files B<stdio.h>, B<openssl/err.h> and B<openssl/xxx.h> so the | |
c8973693 | 155 | header file must load any additional header files containing any |
54a34aec DSH |
156 | definitions it uses. |
157 | ||
158 | =head1 USING ERROR CODES IN EXTERNAL LIBRARIES | |
159 | ||
160 | It is also possible to use OpenSSL's error code scheme in external | |
161 | libraries. The library needs to load its own codes and call the OpenSSL | |
162 | error code insertion script B<mkerr.pl> explicitly to add codes to | |
163 | the header file and generate the C error code file. This will normally | |
164 | be done if the external library needs to generate new ASN1 structures | |
165 | but it can also be used to add more general purpose error code handling. | |
166 | ||
167 | TBA more details | |
168 | ||
388f2f56 UM |
169 | =head1 INTERNALS |
170 | ||
8509dcc9 AG |
171 | The error queues are stored in a thread-local storage with one B<ERR_STATE> |
172 | entry for each thread. ERR_get_state() returns the current thread's | |
388f2f56 UM |
173 | B<ERR_STATE>. An B<ERR_STATE> can hold up to B<ERR_NUM_ERRORS> error |
174 | codes. When more error codes are added, the old ones are overwritten, | |
175 | on the assumption that the most recent errors are most important. | |
176 | ||
8509dcc9 AG |
177 | Error strings are also stored in a hash table that can be obtained |
178 | by calling ERR_get_string_table(void). | |
388f2f56 UM |
179 | |
180 | =head1 SEE ALSO | |
181 | ||
9b86974e RS |
182 | L<CRYPTO_set_locking_callback(3)>, |
183 | L<ERR_get_error(3)>, | |
184 | L<ERR_GET_LIB(3)>, | |
185 | L<ERR_clear_error(3)>, | |
186 | L<ERR_error_string(3)>, | |
187 | L<ERR_print_errors(3)>, | |
188 | L<ERR_load_crypto_strings(3)>, | |
9b86974e RS |
189 | L<ERR_put_error(3)>, |
190 | L<ERR_load_strings(3)>, | |
191 | L<SSL_get_error(3)> | |
388f2f56 | 192 | |
f672aee4 RS |
193 | =head1 HISTORY |
194 | ||
195 | The ERR_load_crypto_strings() function was deprecated in OpenSSL 1.1.0 by | |
196 | OPENSSL_init_crypto(). | |
197 | ||
388f2f56 | 198 | =cut |
e2f92610 RS |
199 | |
200 | =head1 COPYRIGHT | |
201 | ||
202 | Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. | |
203 | ||
204 | Licensed under the OpenSSL license (the "License"). You may not use | |
205 | this file except in compliance with the License. You can obtain a copy | |
206 | in the file LICENSE in the source distribution or at | |
207 | L<https://www.openssl.org/source/license.html>. | |
208 | ||
209 | =cut |