Modernise the ERR functionality further (new functions and deprecations)
[openssl.git] / doc / man3 / ERR_get_error.pod
1 =pod
2
3 =head1 NAME
4
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,
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
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);
19  unsigned long ERR_peek_last_error(void);
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);
23  unsigned long ERR_peek_last_error_line(const char **file, int *line);
24
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
45  unsigned long ERR_get_error_line_data(const char **file, int *line,
46                                        const char **data, int *flags);
47  unsigned long ERR_peek_error_line_data(const char **file, int *line,
48                                         const char **data, int *flags);
49  unsigned long ERR_peek_last_error_line_data(const char **file, int *line,
50                                              const char **data, int *flags);
51
52 =head1 DESCRIPTION
53
54 ERR_get_error() returns the earliest error code from the thread's error
55 queue and removes the entry. This function can be called repeatedly
56 until there are no more error codes to return.
57
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
62 error queue without modifying it.
63
64 See L<ERR_GET_LIB(3)> for obtaining information about
65 location and reason of the error, and
66 L<ERR_error_string(3)> for human-readable error
67 messages.
68
69 ERR_get_error_line(), ERR_peek_error_line() and
70 ERR_peek_last_error_line() are the same as ERR_get_error(),
71 ERR_peek_error() and ERR_peek_last_error(), but they
72 additionally store the file name and line number where
73 the error occurred in *B<file> and *B<line>, unless these are B<NULL>.
74
75 ERR_get_error_func(), ERR_peek_error_func() and
76 ERR_peek_last_error_func() are the same as ERR_get_error(),
77 ERR_peek_error() and ERR_peek_last_error(), but they
78 additionally store the name of the function where the error in *B<func>,
79 unless it is B<NULL>.
80
81 ERR_get_error_data(), ERR_peek_error_data() and
82 ERR_peek_last_error_data() are the same as ERR_get_error(),
83 ERR_peek_error() and ERR_peek_last_error(), but they
84 additionally store additional data and flags associated with the error
85 code in *B<data> and *B<flags>, unless these are B<NULL>.
86 *B<data> contains a string if *B<flags>&B<ERR_TXT_STRING> is true.
87
88 ERR_get_error_all(), ERR_peek_error_all() and
89 ERR_peek_last_error_all() are combinations of all of the above.
90
91 ERR_get_error_line_data(), ERR_peek_error_line_data() and
92 ERR_peek_last_error_line_data() are older variants of ERR_get_error_all(),
93 ERR_peek_error_all() and ERR_peek_last_error_all(), and should no longer
94 be used.
95
96 An application B<MUST NOT> free the *B<data> pointer (or any other pointers
97 returned by these functions) with OPENSSL_free() as freeing is handled
98 automatically by the error library.
99
100 =head1 RETURN VALUES
101
102 The error code, or 0 if there is no error in the queue.
103
104 =head1 SEE ALSO
105
106 L<ERR_error_string(3)>,
107 L<ERR_GET_LIB(3)>
108
109 =head1 HISTORY
110
111 ERR_get_error_func(), ERR_peek_error_func(), ERR_peek_last_error_func(),
112 ERR_get_error_data(), ERR_peek_error_data(), ERR_peek_last_error_data(),
113 ERR_get_error_all(), ERR_peek_error_all() and ERR_peek_last_error_all()
114 were added in OpenSSL 3.0.
115
116 ERR_get_error_line_data(), ERR_peek_error_line_data() and
117 ERR_peek_last_error_line_data() became deprecated in OpenSSL 3.0.
118
119
120 =head1 COPYRIGHT
121
122 Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved.
123
124 Licensed under the Apache License 2.0 (the "License").  You may not use
125 this file except in compliance with the License.  You can obtain a copy
126 in the file LICENSE in the source distribution or at
127 L<https://www.openssl.org/source/license.html>.
128
129 =cut