xref: /openssl/doc/man3/OSSL_ERR_STATE_save.pod (revision 7ed6de99)
1=pod
2
3=head1 NAME
4
5OSSL_ERR_STATE_new, OSSL_ERR_STATE_save, OSSL_ERR_STATE_save_to_mark,
6OSSL_ERR_STATE_restore, OSSL_ERR_STATE_free - saving and restoring error state
7
8=head1 SYNOPSIS
9
10 #include <openssl/err.h>
11
12 ERR_STATE *OSSL_ERR_STATE_new(void);
13 void OSSL_ERR_STATE_save(ERR_STATE *es);
14 void OSSL_ERR_STATE_save_to_mark(ERR_STATE *es);
15 void OSSL_ERR_STATE_restore(const ERR_STATE *es);
16 void OSSL_ERR_STATE_free(ERR_STATE *es);
17
18=head1 DESCRIPTION
19
20These functions save and restore the error state from the thread
21local error state to a preallocated error state structure.
22
23OSSL_ERR_STATE_new() allocates an empty error state structure to
24be used when saving and restoring thread error state.
25
26OSSL_ERR_STATE_save() saves the thread error state to I<es>. It
27subsequently clears the thread error state. Any previously saved
28state in I<es> is cleared prior to saving the new state.
29
30OSSL_ERR_STATE_save_to_mark() is similar to OSSL_ERR_STATE_save() but only saves
31ERR entries up to the most recent mark on the ERR stack. These entries are moved
32to I<es> and removed from the thread error state. However, the most recent
33marked ERR and any ERR state before it remains part of the thread error state
34and is not moved to the ERR_STATE. The mark is not cleared and must be cleared
35explicitly after a call to this function using L<ERR_pop_to_mark(3)> or
36L<ERR_clear_last_mark(3)>. (Since a call to OSSL_ERR_STATE_save_to_mark() leaves
37the marked ERR as the top error, either of these functions will have the same
38effect.) If there is no marked ERR in the thread local error state, all ERR
39entries are copied and the effect is the same as for a call to
40OSSL_ERR_STATE_save().
41
42OSSL_ERR_STATE_restore() adds all the error entries from the
43saved state I<es> to the thread error state. Existing entries in
44the thread error state are not affected if there is enough space
45for all the added entries. Any allocated data in the saved error
46entries is duplicated on adding to the thread state.
47
48OSSL_ERR_STATE_free() frees the saved error state I<es>.
49If the argument is NULL, nothing is done.
50
51=head1 RETURN VALUES
52
53OSSL_ERR_STATE_new() returns a pointer to the allocated ERR_STATE
54structure or NULL on error.
55
56OSSL_ERR_STATE_save(), OSSL_ERR_STATE_save_to_mark(), OSSL_ERR_STATE_restore(),
57OSSL_ERR_STATE_free() do not return any values.
58
59=head1 NOTES
60
61OSSL_ERR_STATE_save() and OSSL_ERR_STATE_save_to_mark() cannot fail as it takes
62over any allocated data from the thread error state.
63
64OSSL_ERR_STATE_restore() is a best effort function. The only failure
65that can happen during its operation is when memory allocation fails.
66Because it manipulates the thread error state it avoids raising memory
67errors on such failure. At worst the restored error entries will be
68missing the auxiliary error data.
69
70=head1 SEE ALSO
71
72L<ERR_raise(3)>, L<ERR_get_error(3)>, L<ERR_clear_error(3)>
73
74=head1 HISTORY
75
76All of these functions were added in OpenSSL 3.2.
77
78=head1 COPYRIGHT
79
80Copyright 2023-2024 The OpenSSL Project Authors. All Rights Reserved.
81
82Licensed under the Apache License 2.0 (the "License").  You may not use
83this file except in compliance with the License.  You can obtain a copy
84in the file LICENSE in the source distribution or at
85L<https://www.openssl.org/source/license.html>.
86
87=cut
88