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

=pod

=head1 NAME

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_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

 #include <openssl/err.h>

 unsigned long ERR_get_error(void);
 unsigned long ERR_peek_error(void);
 unsigned long ERR_peek_last_error(void);

 unsigned long ERR_get_error_line(const char **file, int *line);
 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,
                                        const char **data, int *flags);
 unsigned long ERR_peek_last_error_line_data(const char **file, int *line,
                                             const char **data, int *flags);

=head1 DESCRIPTION

ERR_get_error() returns the earliest error code from the thread's error
queue and removes the entry. This function can be called repeatedly
until there are no more error codes to return.

ERR_peek_error() returns the earliest error code from the thread's
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 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 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() 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
automatically by the error library.

=head1 RETURN VALUES

The error code, or 0 if there is no error in the queue.

=head1 SEE ALSO

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 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>.

=cut
Commit	Line	Data
388f2f56 UM	1	=pod
	2
	3	=head1 NAME
	4
a14e2d9d BM	5	ERR_get_error, ERR_peek_error, ERR_peek_last_error,
a14e2d9d BM	6	ERR_get_error_line, ERR_peek_error_line, ERR_peek_last_error_line,
b13342e9 RL	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
388f2f56 UM	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);
a14e2d9d	19	unsigned long ERR_peek_last_error(void);
388f2f56 UM	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);
a14e2d9d	23	unsigned long ERR_peek_last_error_line(const char *file, int line);
388f2f56	24
b13342e9 RL	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
388f2f56	45	unsigned long ERR_get_error_line_data(const char *file, int line,
e9b77246	46	const char *data, int flags);
388f2f56	47	unsigned long ERR_peek_error_line_data(const char *file, int line,
e9b77246	48	const char *data, int flags);
a14e2d9d	49	unsigned long ERR_peek_last_error_line_data(const char *file, int line,
e9b77246	50	const char *data, int flags);
388f2f56 UM	51
	52	=head1 DESCRIPTION
	53
a14e2d9d	54	ERR_get_error() returns the earliest error code from the thread's error
388f2f56 UM	55	queue and removes the entry. This function can be called repeatedly
	56	until there are no more error codes to return.
	57
a14e2d9d BM	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
388f2f56 UM	62	error queue without modifying it.
388f2f56 UM	63
df082268 DDO	64	See L<ERR_GET_LIB(3)> for obtaining further specific information
	65	such as the reason of the error,
	66	and L<ERR_error_string(3)> for human-readable error messages.
388f2f56	67
a14e2d9d	68	ERR_get_error_line(), ERR_peek_error_line() and
b13342e9	69	ERR_peek_last_error_line() are the same as ERR_get_error(),
df082268	70	ERR_peek_error() and ERR_peek_last_error(), but on success they
9c0586d5	71	additionally store the filename and line number where
df082268	72	the error occurred in B<file> and B<line>, as far as they are not B<NULL>.
9c0586d5	73	An unset filename is indicated as B<"">, i.e., an empty string.
df082268 DDO	74	An unset line number is indicated as B<0>.
	75
	76	A pointer returned this way by these functions and the ones below
	77	is valid until the respective entry is removed from the error queue.
388f2f56	78
b13342e9 RL	79	ERR_get_error_func(), ERR_peek_error_func() and
b13342e9 RL	80	ERR_peek_last_error_func() are the same as ERR_get_error(),
df082268 DDO	81	ERR_peek_error() and ERR_peek_last_error(), but on success they
	82	additionally store the name of the function where the error occurred
	83	in *B<func>, unless it is B<NULL>.
	84	An unset function name is indicated as B<"">.
b13342e9 RL	85
	86	ERR_get_error_data(), ERR_peek_error_data() and
	87	ERR_peek_last_error_data() are the same as ERR_get_error(),
df082268	88	ERR_peek_error() and ERR_peek_last_error(), but on success they
b13342e9	89	additionally store additional data and flags associated with the error
df082268 DDO	90	code in B<data> and B<flags>, as far as they are not B<NULL>.
	91	Unset data is indicated as B<"">.
	92	In this case the value given for the flag is irrelevant (and equals B<0>).
b13342e9 RL	93	B<data> contains a string if B<flags>&B<ERR_TXT_STRING> is true.
	94
	95	ERR_get_error_all(), ERR_peek_error_all() and
	96	ERR_peek_last_error_all() are combinations of all of the above.
	97
a14e2d9d	98	ERR_get_error_line_data(), ERR_peek_error_line_data() and
b13342e9 RL	99	ERR_peek_last_error_line_data() are older variants of ERR_get_error_all(),
	100	ERR_peek_error_all() and ERR_peek_last_error_all(), and should no longer
	101	be used.
30ea570f DSH	102
	103	An application B<MUST NOT> free the *B<data> pointer (or any other pointers
	104	returned by these functions) with OPENSSL_free() as freeing is handled
	105	automatically by the error library.
388f2f56 UM	106
	107	=head1 RETURN VALUES
	108
	109	The error code, or 0 if there is no error in the queue.
	110
	111	=head1 SEE ALSO
	112
73fb82b7	113	L<ERR_error_string(3)>,
9b86974e	114	L<ERR_GET_LIB(3)>
388f2f56	115
b13342e9 RL	116	=head1 HISTORY
	117
	118	ERR_get_error_func(), ERR_peek_error_func(), ERR_peek_last_error_func(),
	119	ERR_get_error_data(), ERR_peek_error_data(), ERR_peek_last_error_data(),
	120	ERR_get_error_all(), ERR_peek_error_all() and ERR_peek_last_error_all()
	121	were added in OpenSSL 3.0.
	122
	123	ERR_get_error_line_data(), ERR_peek_error_line_data() and
	124	ERR_peek_last_error_line_data() became deprecated in OpenSSL 3.0.
	125
	126
e2f92610 RS	127	=head1 COPYRIGHT
e2f92610 RS	128
73fb82b7	129	Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved.
e2f92610	130
4746f25a	131	Licensed under the Apache License 2.0 (the "License"). You may not use
e2f92610 RS	132	this file except in compliance with the License. You can obtain a copy
	133	in the file LICENSE in the source distribution or at
	134	L<https://www.openssl.org/source/license.html>.
	135
	136	=cut