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