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