1*b077aed3SPierre Pronchery=pod 2*b077aed3SPierre Pronchery 3*b077aed3SPierre Pronchery=head1 NAME 4*b077aed3SPierre Pronchery 5*b077aed3SPierre ProncheryERR_new, ERR_set_debug, ERR_set_error, ERR_vset_error 6*b077aed3SPierre Pronchery- Error recording building blocks 7*b077aed3SPierre Pronchery 8*b077aed3SPierre Pronchery=head1 SYNOPSIS 9*b077aed3SPierre Pronchery 10*b077aed3SPierre Pronchery #include <openssl/err.h> 11*b077aed3SPierre Pronchery 12*b077aed3SPierre Pronchery void ERR_new(void); 13*b077aed3SPierre Pronchery void ERR_set_debug(const char *file, int line, const char *func); 14*b077aed3SPierre Pronchery void ERR_set_error(int lib, int reason, const char *fmt, ...); 15*b077aed3SPierre Pronchery void ERR_vset_error(int lib, int reason, const char *fmt, va_list args); 16*b077aed3SPierre Pronchery 17*b077aed3SPierre Pronchery=head1 DESCRIPTION 18*b077aed3SPierre Pronchery 19*b077aed3SPierre ProncheryThe functions described here are generally not used directly, but 20*b077aed3SPierre Proncheryrather through macros such as L<ERR_raise(3)>. 21*b077aed3SPierre ProncheryThey can still be useful for anyone that wants to make their own 22*b077aed3SPierre Proncherymacros. 23*b077aed3SPierre Pronchery 24*b077aed3SPierre ProncheryERR_new() allocates a new slot in the thread's error queue. 25*b077aed3SPierre Pronchery 26*b077aed3SPierre ProncheryERR_set_debug() sets the debug information related to the current 27*b077aed3SPierre Proncheryerror in the thread's error queue. 28*b077aed3SPierre ProncheryThe values that can be given are the filename I<file>, line in the 29*b077aed3SPierre Proncheryfile I<line> and the name of the function I<func> where the error 30*b077aed3SPierre Proncheryoccurred. 31*b077aed3SPierre ProncheryThe names must be constant, this function will only save away the 32*b077aed3SPierre Proncherypointers, not copy the strings. 33*b077aed3SPierre Pronchery 34*b077aed3SPierre ProncheryERR_set_error() sets the error information, which are the library 35*b077aed3SPierre Proncherynumber I<lib> and the reason code I<reason>, and additional data as a 36*b077aed3SPierre Proncheryformat string I<fmt> and an arbitrary number of arguments. 37*b077aed3SPierre ProncheryThe additional data is processed with L<BIO_snprintf(3)> to form the 38*b077aed3SPierre Proncheryadditional data string, which is allocated and store in the error 39*b077aed3SPierre Proncheryrecord. 40*b077aed3SPierre Pronchery 41*b077aed3SPierre ProncheryERR_vset_error() works like ERR_set_error(), but takes a B<va_list> 42*b077aed3SPierre Proncheryargument instead of a variable number of arguments. 43*b077aed3SPierre Pronchery 44*b077aed3SPierre Pronchery=head1 RETURN VALUES 45*b077aed3SPierre Pronchery 46*b077aed3SPierre ProncheryERR_new, ERR_set_debug, ERR_set_error and ERR_vset_error 47*b077aed3SPierre Proncherydo not return any values. 48*b077aed3SPierre Pronchery 49*b077aed3SPierre Pronchery=head1 NOTES 50*b077aed3SPierre Pronchery 51*b077aed3SPierre ProncheryThe library number is unique to each unit that records errors. 52*b077aed3SPierre ProncheryOpenSSL has a number of preallocated ones for its own uses, but 53*b077aed3SPierre Proncheryothers may allocate their own library number dynamically with 54*b077aed3SPierre ProncheryL<ERR_get_next_error_library(3)>. 55*b077aed3SPierre Pronchery 56*b077aed3SPierre ProncheryReason codes are unique within each library, and may have an 57*b077aed3SPierre Proncheryassociated set of strings as a short description of the reason. 58*b077aed3SPierre ProncheryFor dynamically allocated library numbers, reason strings are recorded 59*b077aed3SPierre Proncherywith L<ERR_load_strings(3)>. 60*b077aed3SPierre Pronchery 61*b077aed3SPierre ProncheryProvider authors are supplied with core versions of these functions, 62*b077aed3SPierre Proncherysee L<provider-base(7)>. 63*b077aed3SPierre Pronchery 64*b077aed3SPierre Pronchery=head1 SEE ALSO 65*b077aed3SPierre Pronchery 66*b077aed3SPierre ProncheryL<ERR_raise(3)>, L<ERR_get_next_error_library(3)>, 67*b077aed3SPierre ProncheryL<ERR_load_strings(3)>, L<BIO_snprintf(3)>, L<provider-base(7)> 68*b077aed3SPierre Pronchery 69*b077aed3SPierre Pronchery=head1 COPYRIGHT 70*b077aed3SPierre Pronchery 71*b077aed3SPierre ProncheryCopyright 2000-2020 The OpenSSL Project Authors. All Rights Reserved. 72*b077aed3SPierre Pronchery 73*b077aed3SPierre ProncheryLicensed under the Apache License 2.0 (the "License"). You may not use 74*b077aed3SPierre Proncherythis file except in compliance with the License. You can obtain a copy 75*b077aed3SPierre Proncheryin the file LICENSE in the source distribution or at 76*b077aed3SPierre ProncheryL<https://www.openssl.org/source/license.html>. 77*b077aed3SPierre Pronchery 78*b077aed3SPierre Pronchery=cut 79