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