ERR_get_error.pod 5.4 KB

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