]>
Commit | Line | Data |
---|---|---|
388f2f56 UM |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
ed57f7f9 | 5 | ERR_raise, ERR_raise_data, |
31b28ad9 DDO |
6 | ERR_put_error, ERR_add_error_data, ERR_add_error_vdata, |
7 | ERR_add_error_txt, ERR_add_error_mem_bio | |
add8c8e9 | 8 | - record an error |
388f2f56 UM |
9 | |
10 | =head1 SYNOPSIS | |
11 | ||
12 | #include <openssl/err.h> | |
13 | ||
ed57f7f9 RL |
14 | void ERR_raise(int lib, int reason); |
15 | void ERR_raise_data(int lib, int reason, const char *fmt, ...); | |
16 | ||
388f2f56 | 17 | void ERR_add_error_data(int num, ...); |
61ced34f | 18 | void ERR_add_error_vdata(int num, va_list arg); |
31b28ad9 DDO |
19 | void ERR_add_error_txt(const char *sep, const char *txt); |
20 | void ERR_add_error_mem_bio(const char *sep, BIO *bio); | |
388f2f56 | 21 | |
add8c8e9 RL |
22 | Deprecated since OpenSSL 3.0: |
23 | ||
24 | void ERR_put_error(int lib, int func, int reason, const char *file, int line); | |
25 | ||
388f2f56 UM |
26 | =head1 DESCRIPTION |
27 | ||
ed57f7f9 | 28 | ERR_raise() adds a new error to the thread's error queue. The |
79c44b4e | 29 | error occurred in the library B<lib> for the reason given by the |
ed57f7f9 | 30 | B<reason> code. Furthermore, the name of the file, the line, and name |
79c44b4e | 31 | of the function where the error occurred is saved with the error |
ed57f7f9 RL |
32 | record. |
33 | ||
34 | ERR_raise_data() does the same thing as ERR_raise(), but also lets the | |
35 | caller specify additional information as a format string B<fmt> and an | |
36 | arbitrary number of values, which are processed with L<BIO_snprintf(3)>. | |
37 | ||
388f2f56 UM |
38 | ERR_put_error() adds an error code to the thread's error queue. It |
39 | signals that the error of reason code B<reason> occurred in function | |
40 | B<func> of library B<lib>, in line number B<line> of B<file>. | |
41 | This function is usually called by a macro. | |
42 | ||
43 | ERR_add_error_data() associates the concatenation of its B<num> string | |
31b28ad9 | 44 | arguments as additional data with the error code added last. |
c952780c | 45 | ERR_add_error_vdata() is similar except the argument is a B<va_list>. |
8908d18c | 46 | Multiple calls to these functions append to the current top of the error queue. |
31b28ad9 DDO |
47 | The total length of the string data per error is limited to 4096 characters. |
48 | ||
49 | ERR_add_error_txt() appends the given text string as additional data to the | |
50 | last error queue entry, after inserting the optional separator string if it is | |
51 | not NULL and the top error entry does not yet have additional data. | |
52 | In case the separator is at the end of the text it is not appended to the data. | |
53 | The B<sep> argument may be for instance "\n" to insert a line break when needed. | |
54 | If the associated data would become more than 4096 characters long | |
55 | (which is the limit given above) | |
56 | it is split over sufficiently many new copies of the last error queue entry. | |
57 | ||
58 | ERR_add_error_mem_bio() is the same as ERR_add_error_txt() except that | |
59 | the text string is taken from the given memory BIO. | |
60 | It appends '\0' to the BIO contents if not already NUL-terminated. | |
388f2f56 | 61 | |
9b86974e | 62 | L<ERR_load_strings(3)> can be used to register |
388f2f56 UM |
63 | error strings so that the application can a generate human-readable |
64 | error messages for the error code. | |
65 | ||
53934822 RS |
66 | =head2 Reporting errors |
67 | ||
add8c8e9 RL |
68 | =for comment TODO(3.0) should this be internal documentation? |
69 | ||
53934822 RS |
70 | Each sub-library has a specific macro XXXerr() that is used to report |
71 | errors. Its first argument is a function code B<XXX_F_...>, the second | |
72 | argument is a reason code B<XXX_R_...>. Function codes are derived | |
73 | from the function names; reason codes consist of textual error | |
74 | descriptions. For example, the function ssl3_read_bytes() reports a | |
75 | "handshake failure" as follows: | |
76 | ||
77 | SSLerr(SSL_F_SSL3_READ_BYTES, SSL_R_SSL_HANDSHAKE_FAILURE); | |
78 | ||
9c0586d5 | 79 | Function and reason codes should consist of uppercase characters, |
53934822 RS |
80 | numbers and underscores only. The error file generation script translates |
81 | function codes into function names by looking in the header files | |
82 | for an appropriate function name, if none is found it just uses | |
83 | the capitalized form such as "SSL3_READ_BYTES" in the above example. | |
84 | ||
85 | The trailing section of a reason code (after the "_R_") is translated | |
9c0586d5 | 86 | into lowercase and underscores changed to spaces. |
53934822 | 87 | |
53934822 RS |
88 | Although a library will normally report errors using its own specific |
89 | XXXerr macro, another library's macro can be used. This is normally | |
90 | only done when a library wants to include ASN1 code which must use | |
91 | the ASN1err() macro. | |
92 | ||
93 | ||
388f2f56 UM |
94 | =head1 RETURN VALUES |
95 | ||
31b28ad9 DDO |
96 | ERR_raise(), ERR_put_error(), |
97 | ERR_add_error_data(), ERR_add_error_vdata() | |
98 | ERR_add_error_txt(), and ERR_add_error_mem_bio() | |
99 | return no values. | |
ed57f7f9 RL |
100 | |
101 | =head1 NOTES | |
102 | ||
add8c8e9 | 103 | ERR_raise() and ERR_put_error() are implemented as macros. |
388f2f56 UM |
104 | |
105 | =head1 SEE ALSO | |
106 | ||
73fb82b7 | 107 | L<ERR_load_strings(3)> |
388f2f56 | 108 | |
31b28ad9 DDO |
109 | =head1 HISTORY |
110 | ||
111 | B<ERR_add_error_txt> and B<ERR_add_error_mem_bio> were added in OpenSSL 3.0. | |
112 | ||
e2f92610 RS |
113 | =head1 COPYRIGHT |
114 | ||
ed57f7f9 | 115 | Copyright 2000-2019 The OpenSSL Project Authors. All Rights Reserved. |
e2f92610 | 116 | |
4746f25a | 117 | Licensed under the Apache License 2.0 (the "License"). You may not use |
e2f92610 RS |
118 | this file except in compliance with the License. You can obtain a copy |
119 | in the file LICENSE in the source distribution or at | |
120 | L<https://www.openssl.org/source/license.html>. | |
121 | ||
122 | =cut |