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