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