]>
Commit | Line | Data |
---|---|---|
388f2f56 UM |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
a14e2d9d BM |
5 | ERR_get_error, ERR_peek_error, ERR_peek_last_error, |
6 | ERR_get_error_line, ERR_peek_error_line, ERR_peek_last_error_line, | |
b13342e9 RL |
7 | ERR_get_error_func, ERR_peek_error_func, ERR_peek_last_error_func, |
8 | ERR_get_error_data, ERR_peek_error_data, ERR_peek_last_error_data, | |
9 | ERR_get_error_all, ERR_peek_error_all, ERR_peek_last_error_all, | |
10 | ERR_get_error_line_data, ERR_peek_error_line_data, ERR_peek_last_error_line_data | |
11 | - obtain error code and data | |
388f2f56 UM |
12 | |
13 | =head1 SYNOPSIS | |
14 | ||
15 | #include <openssl/err.h> | |
16 | ||
17 | unsigned long ERR_get_error(void); | |
18 | unsigned long ERR_peek_error(void); | |
a14e2d9d | 19 | unsigned long ERR_peek_last_error(void); |
388f2f56 UM |
20 | |
21 | unsigned long ERR_get_error_line(const char **file, int *line); | |
22 | unsigned long ERR_peek_error_line(const char **file, int *line); | |
a14e2d9d | 23 | unsigned long ERR_peek_last_error_line(const char **file, int *line); |
388f2f56 | 24 | |
b13342e9 RL |
25 | unsigned long ERR_get_error_func(const char **func); |
26 | unsigned long ERR_peek_error_func(const char **func); | |
27 | unsigned long ERR_peek_last_error_func(const char **func); | |
28 | ||
29 | unsigned long ERR_get_error_data(const char **data, int *flags); | |
30 | unsigned long ERR_peek_error_data(const char **data, int *flags); | |
31 | unsigned long ERR_peek_last_error_data(const char **data, int *flags); | |
32 | ||
33 | unsigned long ERR_get_error_all(const char **file, int *line, | |
34 | const char *func, | |
35 | const char **data, int *flags); | |
36 | unsigned long ERR_peek_error_all(const char **file, int *line, | |
37 | const char *func, | |
38 | const char **data, int *flags); | |
39 | unsigned long ERR_peek_last_error_all(const char **file, int *line, | |
40 | const char *func, | |
41 | const char **data, int *flags); | |
42 | ||
43 | Deprecated since OpenSSL 3.0: | |
44 | ||
388f2f56 | 45 | unsigned long ERR_get_error_line_data(const char **file, int *line, |
e9b77246 | 46 | const char **data, int *flags); |
388f2f56 | 47 | unsigned long ERR_peek_error_line_data(const char **file, int *line, |
e9b77246 | 48 | const char **data, int *flags); |
a14e2d9d | 49 | unsigned long ERR_peek_last_error_line_data(const char **file, int *line, |
e9b77246 | 50 | const char **data, int *flags); |
388f2f56 UM |
51 | |
52 | =head1 DESCRIPTION | |
53 | ||
a14e2d9d | 54 | ERR_get_error() returns the earliest error code from the thread's error |
388f2f56 UM |
55 | queue and removes the entry. This function can be called repeatedly |
56 | until there are no more error codes to return. | |
57 | ||
a14e2d9d BM |
58 | ERR_peek_error() returns the earliest error code from the thread's |
59 | error queue without modifying it. | |
60 | ||
61 | ERR_peek_last_error() returns the latest error code from the thread's | |
388f2f56 UM |
62 | error queue without modifying it. |
63 | ||
df082268 DDO |
64 | See L<ERR_GET_LIB(3)> for obtaining further specific information |
65 | such as the reason of the error, | |
66 | and L<ERR_error_string(3)> for human-readable error messages. | |
388f2f56 | 67 | |
a14e2d9d | 68 | ERR_get_error_line(), ERR_peek_error_line() and |
b13342e9 | 69 | ERR_peek_last_error_line() are the same as ERR_get_error(), |
df082268 | 70 | ERR_peek_error() and ERR_peek_last_error(), but on success they |
9c0586d5 | 71 | additionally store the filename and line number where |
df082268 | 72 | the error occurred in *B<file> and *B<line>, as far as they are not B<NULL>. |
9c0586d5 | 73 | An unset filename is indicated as B<"">, i.e., an empty string. |
df082268 DDO |
74 | An unset line number is indicated as B<0>. |
75 | ||
76 | A pointer returned this way by these functions and the ones below | |
77 | is valid until the respective entry is removed from the error queue. | |
388f2f56 | 78 | |
b13342e9 RL |
79 | ERR_get_error_func(), ERR_peek_error_func() and |
80 | ERR_peek_last_error_func() are the same as ERR_get_error(), | |
df082268 DDO |
81 | ERR_peek_error() and ERR_peek_last_error(), but on success they |
82 | additionally store the name of the function where the error occurred | |
83 | in *B<func>, unless it is B<NULL>. | |
84 | An unset function name is indicated as B<"">. | |
b13342e9 RL |
85 | |
86 | ERR_get_error_data(), ERR_peek_error_data() and | |
87 | ERR_peek_last_error_data() are the same as ERR_get_error(), | |
df082268 | 88 | ERR_peek_error() and ERR_peek_last_error(), but on success they |
b13342e9 | 89 | additionally store additional data and flags associated with the error |
df082268 DDO |
90 | code in *B<data> and *B<flags>, as far as they are not B<NULL>. |
91 | Unset data is indicated as B<"">. | |
92 | In this case the value given for the flag is irrelevant (and equals B<0>). | |
b13342e9 RL |
93 | *B<data> contains a string if *B<flags>&B<ERR_TXT_STRING> is true. |
94 | ||
95 | ERR_get_error_all(), ERR_peek_error_all() and | |
96 | ERR_peek_last_error_all() are combinations of all of the above. | |
97 | ||
a14e2d9d | 98 | ERR_get_error_line_data(), ERR_peek_error_line_data() and |
b13342e9 RL |
99 | ERR_peek_last_error_line_data() are older variants of ERR_get_error_all(), |
100 | ERR_peek_error_all() and ERR_peek_last_error_all(), and should no longer | |
101 | be used. | |
30ea570f DSH |
102 | |
103 | An application B<MUST NOT> free the *B<data> pointer (or any other pointers | |
104 | returned by these functions) with OPENSSL_free() as freeing is handled | |
105 | automatically by the error library. | |
388f2f56 UM |
106 | |
107 | =head1 RETURN VALUES | |
108 | ||
109 | The error code, or 0 if there is no error in the queue. | |
110 | ||
111 | =head1 SEE ALSO | |
112 | ||
73fb82b7 | 113 | L<ERR_error_string(3)>, |
9b86974e | 114 | L<ERR_GET_LIB(3)> |
388f2f56 | 115 | |
b13342e9 RL |
116 | =head1 HISTORY |
117 | ||
118 | ERR_get_error_func(), ERR_peek_error_func(), ERR_peek_last_error_func(), | |
119 | ERR_get_error_data(), ERR_peek_error_data(), ERR_peek_last_error_data(), | |
120 | ERR_get_error_all(), ERR_peek_error_all() and ERR_peek_last_error_all() | |
121 | were added in OpenSSL 3.0. | |
122 | ||
123 | ERR_get_error_line_data(), ERR_peek_error_line_data() and | |
124 | ERR_peek_last_error_line_data() became deprecated in OpenSSL 3.0. | |
125 | ||
126 | ||
e2f92610 RS |
127 | =head1 COPYRIGHT |
128 | ||
73fb82b7 | 129 | Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved. |
e2f92610 | 130 | |
4746f25a | 131 | Licensed under the Apache License 2.0 (the "License"). You may not use |
e2f92610 RS |
132 | this file except in compliance with the License. You can obtain a copy |
133 | in the file LICENSE in the source distribution or at | |
134 | L<https://www.openssl.org/source/license.html>. | |
135 | ||
136 | =cut |