Update documentation

[openssl.git] / doc / man3 / ERR_get_error.pod

diff --git a/doc/man3/ERR_get_error.pod b/doc/man3/ERR_get_error.pod
index a76df03882d8e56ee9c12e7d79839c160afdfc05..97478dbe7ca1b13cb888b9d1457e8d2c397c82ea 100644 (file)
--- a/doc/man3/ERR_get_error.pod
+++ b/doc/man3/ERR_get_error.pod
@@ -4,8 +4,11 @@
 
 ERR_get_error, ERR_peek_error, ERR_peek_last_error,
 ERR_get_error_line, ERR_peek_error_line, ERR_peek_last_error_line,
-ERR_get_error_line_data, ERR_peek_error_line_data,
-ERR_peek_last_error_line_data - obtain error code and data
+ERR_get_error_func, ERR_peek_error_func, ERR_peek_last_error_func,
+ERR_get_error_data, ERR_peek_error_data, ERR_peek_last_error_data,
+ERR_get_error_all, ERR_peek_error_all, ERR_peek_last_error_all,
+ERR_get_error_line_data, ERR_peek_error_line_data, ERR_peek_last_error_line_data
+- obtain error code and data
 
 =head1 SYNOPSIS
 
@@ -19,6 +22,26 @@ ERR_peek_last_error_line_data - obtain error code and data
  unsigned long ERR_peek_error_line(const char **file, int *line);
  unsigned long ERR_peek_last_error_line(const char **file, int *line);
 
+ unsigned long ERR_get_error_func(const char **func);
+ unsigned long ERR_peek_error_func(const char **func);
+ unsigned long ERR_peek_last_error_func(const char **func);
+
+ unsigned long ERR_get_error_data(const char **data, int *flags);
+ unsigned long ERR_peek_error_data(const char **data, int *flags);
+ unsigned long ERR_peek_last_error_data(const char **data, int *flags);
+
+ unsigned long ERR_get_error_all(const char **file, int *line,
+                                 const char *func,
+                                 const char **data, int *flags);
+ unsigned long ERR_peek_error_all(const char **file, int *line,
+                                  const char *func,
+                                  const char **data, int *flags);
+ unsigned long ERR_peek_last_error_all(const char **file, int *line,
+                                       const char *func,
+                                       const char **data, int *flags);
+
+Deprecated since OpenSSL 3.0:
+
  unsigned long ERR_get_error_line_data(const char **file, int *line,
                                        const char **data, int *flags);
  unsigned long ERR_peek_error_line_data(const char **file, int *line,
@@ -38,21 +61,44 @@ error queue without modifying it.
 ERR_peek_last_error() returns the latest error code from the thread's
 error queue without modifying it.
 
-See L<ERR_GET_LIB(3)> for obtaining information about
-location and reason of the error, and
-L<ERR_error_string(3)> for human-readable error
-messages.
+See L<ERR_GET_LIB(3)> for obtaining further specific information
+such as the reason of the error,
+and L<ERR_error_string(3)> for human-readable error messages.
 
 ERR_get_error_line(), ERR_peek_error_line() and
-ERR_peek_last_error_line() are the same as the above, but they
-additionally store the file name and line number where
-the error occurred in *B<file> and *B<line>, unless these are B<NULL>.
+ERR_peek_last_error_line() are the same as ERR_get_error(),
+ERR_peek_error() and ERR_peek_last_error(), but on success they
+additionally store the filename and line number where
+the error occurred in *B<file> and *B<line>, as far as they are not B<NULL>.
+An unset filename is indicated as B<"">, i.e., an empty string.
+An unset line number is indicated as B<0>.
+
+A pointer returned this way by these functions and the ones below
+is valid until the respective entry is removed from the error queue.
+
+ERR_get_error_func(), ERR_peek_error_func() and
+ERR_peek_last_error_func() are the same as ERR_get_error(),
+ERR_peek_error() and ERR_peek_last_error(), but on success they
+additionally store the name of the function where the error occurred
+in *B<func>, unless it is B<NULL>.
+An unset function name is indicated as B<"">.
+
+ERR_get_error_data(), ERR_peek_error_data() and
+ERR_peek_last_error_data() are the same as ERR_get_error(),
+ERR_peek_error() and ERR_peek_last_error(), but on success they
+additionally store additional data and flags associated with the error
+code in *B<data> and *B<flags>, as far as they are not B<NULL>.
+Unset data is indicated as B<"">.
+In this case the value given for the flag is irrelevant (and equals B<0>).
+*B<data> contains a string if *B<flags>&B<ERR_TXT_STRING> is true.
+
+ERR_get_error_all(), ERR_peek_error_all() and
+ERR_peek_last_error_all() are combinations of all of the above.
 
 ERR_get_error_line_data(), ERR_peek_error_line_data() and
-ERR_peek_last_error_line_data() store additional data and flags
-associated with the error code in *B<data>
-and *B<flags>, unless these are B<NULL>. *B<data> contains a string
-if *B<flags>&B<ERR_TXT_STRING> is true.
+ERR_peek_last_error_line_data() are older variants of ERR_get_error_all(),
+ERR_peek_error_all() and ERR_peek_last_error_all(), and should no longer
+be used.
 
 An application B<MUST NOT> free the *B<data> pointer (or any other pointers
 returned by these functions) with OPENSSL_free() as freeing is handled
@@ -67,11 +113,22 @@ The error code, or 0 if there is no error in the queue.
 L<ERR_error_string(3)>,
 L<ERR_GET_LIB(3)>
 
+=head1 HISTORY
+
+ERR_get_error_func(), ERR_peek_error_func(), ERR_peek_last_error_func(),
+ERR_get_error_data(), ERR_peek_error_data(), ERR_peek_last_error_data(),
+ERR_get_error_all(), ERR_peek_error_all() and ERR_peek_last_error_all()
+were added in OpenSSL 3.0.
+
+ERR_get_error_line_data(), ERR_peek_error_line_data() and
+ERR_peek_last_error_line_data() became deprecated in OpenSSL 3.0.
+
+
 =head1 COPYRIGHT
 
 Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved.
 
-Licensed under the OpenSSL license (the "License").  You may not use
+Licensed under the Apache License 2.0 (the "License").  You may not use
 this file except in compliance with the License.  You can obtain a copy
 in the file LICENSE in the source distribution or at
 L<https://www.openssl.org/source/license.html>.