xref: /freebsd-src/crypto/openssl/doc/man3/ERR_get_error.pod (revision b077aed33b7b6aefca7b17ddb250cf521f938613)
1e71b7053SJung-uk Kim=pod
2e71b7053SJung-uk Kim
3e71b7053SJung-uk Kim=head1 NAME
4e71b7053SJung-uk Kim
5e71b7053SJung-uk KimERR_get_error, ERR_peek_error, ERR_peek_last_error,
6e71b7053SJung-uk KimERR_get_error_line, ERR_peek_error_line, ERR_peek_last_error_line,
7*b077aed3SPierre ProncheryERR_peek_error_func, ERR_peek_last_error_func,
8*b077aed3SPierre ProncheryERR_peek_error_data, ERR_peek_last_error_data,
9*b077aed3SPierre ProncheryERR_get_error_all, ERR_peek_error_all, ERR_peek_last_error_all,
10*b077aed3SPierre ProncheryERR_get_error_line_data, ERR_peek_error_line_data, ERR_peek_last_error_line_data
11*b077aed3SPierre Pronchery- obtain error code and data
12e71b7053SJung-uk Kim
13e71b7053SJung-uk Kim=head1 SYNOPSIS
14e71b7053SJung-uk Kim
15e71b7053SJung-uk Kim #include <openssl/err.h>
16e71b7053SJung-uk Kim
17e71b7053SJung-uk Kim unsigned long ERR_get_error(void);
18e71b7053SJung-uk Kim unsigned long ERR_peek_error(void);
19e71b7053SJung-uk Kim unsigned long ERR_peek_last_error(void);
20e71b7053SJung-uk Kim
21e71b7053SJung-uk Kim unsigned long ERR_peek_error_line(const char **file, int *line);
22e71b7053SJung-uk Kim unsigned long ERR_peek_last_error_line(const char **file, int *line);
23e71b7053SJung-uk Kim
24*b077aed3SPierre Pronchery unsigned long ERR_peek_error_func(const char **func);
25*b077aed3SPierre Pronchery unsigned long ERR_peek_last_error_func(const char **func);
26*b077aed3SPierre Pronchery
27*b077aed3SPierre Pronchery unsigned long ERR_peek_error_data(const char **data, int *flags);
28*b077aed3SPierre Pronchery unsigned long ERR_peek_last_error_data(const char **data, int *flags);
29*b077aed3SPierre Pronchery
30*b077aed3SPierre Pronchery unsigned long ERR_get_error_all(const char **file, int *line,
31*b077aed3SPierre Pronchery                                 const char **func,
32*b077aed3SPierre Pronchery                                 const char **data, int *flags);
33*b077aed3SPierre Pronchery unsigned long ERR_peek_error_all(const char **file, int *line,
34*b077aed3SPierre Pronchery                                  const char **func,
35*b077aed3SPierre Pronchery                                  const char **data, int *flags);
36*b077aed3SPierre Pronchery unsigned long ERR_peek_last_error_all(const char **file, int *line,
37*b077aed3SPierre Pronchery                                       const char *func,
38*b077aed3SPierre Pronchery                                       const char **data, int *flags);
39*b077aed3SPierre Pronchery
40*b077aed3SPierre ProncheryThe following functions have been deprecated since OpenSSL 3.0, and can be
41*b077aed3SPierre Proncheryhidden entirely by defining B<OPENSSL_API_COMPAT> with a suitable version value,
42*b077aed3SPierre Proncherysee L<openssl_user_macros(7)>:
43*b077aed3SPierre Pronchery
44*b077aed3SPierre Pronchery unsigned long ERR_get_error_line(const char **file, int *line);
45e71b7053SJung-uk Kim unsigned long ERR_get_error_line_data(const char **file, int *line,
46e71b7053SJung-uk Kim                                       const char **data, int *flags);
47e71b7053SJung-uk Kim unsigned long ERR_peek_error_line_data(const char **file, int *line,
48e71b7053SJung-uk Kim                                        const char **data, int *flags);
49e71b7053SJung-uk Kim unsigned long ERR_peek_last_error_line_data(const char **file, int *line,
50e71b7053SJung-uk Kim                                             const char **data, int *flags);
51e71b7053SJung-uk Kim
52e71b7053SJung-uk Kim=head1 DESCRIPTION
53e71b7053SJung-uk Kim
54e71b7053SJung-uk KimERR_get_error() returns the earliest error code from the thread's error
55e71b7053SJung-uk Kimqueue and removes the entry.  This function can be called repeatedly
56e71b7053SJung-uk Kimuntil there are no more error codes to return.
57e71b7053SJung-uk Kim
58e71b7053SJung-uk KimERR_peek_error() returns the earliest error code from the thread's
59e71b7053SJung-uk Kimerror queue without modifying it.
60e71b7053SJung-uk Kim
61e71b7053SJung-uk KimERR_peek_last_error() returns the latest error code from the thread's
62e71b7053SJung-uk Kimerror queue without modifying it.
63e71b7053SJung-uk Kim
64*b077aed3SPierre ProncherySee L<ERR_GET_LIB(3)> for obtaining further specific information
65*b077aed3SPierre Proncherysuch as the reason of the error,
66*b077aed3SPierre Proncheryand L<ERR_error_string(3)> for human-readable error messages.
67e71b7053SJung-uk Kim
68*b077aed3SPierre ProncheryERR_get_error_all() is the same as ERR_get_error(), but on success it
69*b077aed3SPierre Proncheryadditionally stores the filename, line number and function where the error
70*b077aed3SPierre Proncheryoccurred in *I<file>, *I<line> and *I<func>, and also extra text and flags
71*b077aed3SPierre Proncheryin *I<data>, *I<flags>.  If any of those parameters are NULL, it will not
72*b077aed3SPierre Proncherybe changed.
73*b077aed3SPierre ProncheryAn unset filename is indicated as "", i.e. an empty string.
74*b077aed3SPierre ProncheryAn unset line number is indicated as 0.
75*b077aed3SPierre ProncheryAn unset function name is indicated as "", i.e. an empty string.
76e71b7053SJung-uk Kim
77*b077aed3SPierre ProncheryA pointer returned this way by these functions and the ones below
78*b077aed3SPierre Proncheryis valid until the respective entry is overwritten in the error queue.
79e71b7053SJung-uk Kim
80*b077aed3SPierre ProncheryERR_peek_error_line() and ERR_peek_last_error_line() are the same as
81*b077aed3SPierre ProncheryERR_peek_error() and ERR_peek_last_error(), but on success they additionally
82*b077aed3SPierre Proncherystore the filename and line number where the error occurred in *I<file> and
83*b077aed3SPierre Pronchery*I<line>, as far as they are not NULL.
84*b077aed3SPierre ProncheryAn unset filename is indicated as "", i.e., an empty string.
85*b077aed3SPierre ProncheryAn unset line number is indicated as 0.
86*b077aed3SPierre Pronchery
87*b077aed3SPierre ProncheryERR_peek_error_func() and ERR_peek_last_error_func() are the same as
88*b077aed3SPierre ProncheryERR_peek_error() and ERR_peek_last_error(), but on success they additionally
89*b077aed3SPierre Proncherystore the name of the function where the error occurred in *I<func>, unless
90*b077aed3SPierre Proncheryit is NULL.
91*b077aed3SPierre ProncheryAn unset function name is indicated as "".
92*b077aed3SPierre Pronchery
93*b077aed3SPierre ProncheryERR_peek_error_data() and ERR_peek_last_error_data() are the same as
94*b077aed3SPierre ProncheryERR_peek_error() and ERR_peek_last_error(), but on success they additionally
95*b077aed3SPierre Proncherystore additional data and flags associated with the error code in *I<data>
96*b077aed3SPierre Proncheryand *I<flags>, as far as they are not NULL.
97*b077aed3SPierre ProncheryUnset data is indicated as "".
98*b077aed3SPierre ProncheryIn this case the value given for the flag is irrelevant (and equals 0).
99*b077aed3SPierre Pronchery*I<data> contains a string if *I<flags>&B<ERR_TXT_STRING> is true.
100*b077aed3SPierre Pronchery
101*b077aed3SPierre ProncheryERR_peek_error_all() and ERR_peek_last_error_all() are combinations of all
102*b077aed3SPierre Proncheryof the above.
103*b077aed3SPierre Pronchery
104*b077aed3SPierre ProncheryERR_get_error_line(), ERR_get_error_line_data(), ERR_peek_error_line_data()
105*b077aed3SPierre Proncheryand ERR_peek_last_error_line_data() are older variants of ERR_get_error_all(),
106*b077aed3SPierre ProncheryERR_peek_error_all() and ERR_peek_last_error_all(), and may give confusing
107*b077aed3SPierre Proncheryresults.  They should no longer be used and are therefore deprecated.
108*b077aed3SPierre Pronchery
109*b077aed3SPierre ProncheryAn application B<MUST NOT> free the *I<data> pointer (or any other pointers
110e71b7053SJung-uk Kimreturned by these functions) with OPENSSL_free() as freeing is handled
111e71b7053SJung-uk Kimautomatically by the error library.
112e71b7053SJung-uk Kim
113e71b7053SJung-uk Kim=head1 RETURN VALUES
114e71b7053SJung-uk Kim
115e71b7053SJung-uk KimThe error code, or 0 if there is no error in the queue.
116e71b7053SJung-uk Kim
117e71b7053SJung-uk Kim=head1 SEE ALSO
118e71b7053SJung-uk Kim
119e71b7053SJung-uk KimL<ERR_error_string(3)>,
120e71b7053SJung-uk KimL<ERR_GET_LIB(3)>
121e71b7053SJung-uk Kim
122*b077aed3SPierre Pronchery=head1 HISTORY
123*b077aed3SPierre Pronchery
124*b077aed3SPierre ProncheryERR_peek_error_func(), ERR_peek_last_error_func(),
125*b077aed3SPierre ProncheryERR_peek_error_data(), ERR_peek_last_error_data(),
126*b077aed3SPierre ProncheryERR_peek_error_all() and ERR_peek_last_error_all()
127*b077aed3SPierre Proncherywere added in OpenSSL 3.0.
128*b077aed3SPierre Pronchery
129*b077aed3SPierre ProncheryERR_get_error_line(), ERR_get_error_line_data(), ERR_peek_error_line_data()
130*b077aed3SPierre Proncheryand ERR_peek_last_error_line_data() became deprecated in OpenSSL 3.0.
131*b077aed3SPierre Pronchery
132*b077aed3SPierre Pronchery
133e71b7053SJung-uk Kim=head1 COPYRIGHT
134e71b7053SJung-uk Kim
135*b077aed3SPierre ProncheryCopyright 2000-2022 The OpenSSL Project Authors. All Rights Reserved.
136e71b7053SJung-uk Kim
137*b077aed3SPierre ProncheryLicensed under the Apache License 2.0 (the "License").  You may not use
138e71b7053SJung-uk Kimthis file except in compliance with the License.  You can obtain a copy
139e71b7053SJung-uk Kimin the file LICENSE in the source distribution or at
140e71b7053SJung-uk KimL<https://www.openssl.org/source/license.html>.
141e71b7053SJung-uk Kim
142e71b7053SJung-uk Kim=cut
143