1=pod 2 3=head1 NAME 4 5ossl_namemap_new, ossl_namemap_free, ossl_namemap_stored, ossl_namemap_empty, 6ossl_namemap_add_name, ossl_namemap_add_name_n, ossl_namemap_add_names, 7ossl_namemap_name2num, ossl_namemap_name2num_n, 8ossl_namemap_doall_names 9- internal number E<lt>-E<gt> name map 10 11=head1 SYNOPSIS 12 13 #include "internal/cryptlib.h" 14 15 OSSL_NAMEMAP *ossl_namemap_stored(OSSL_LIB_CTX *libctx); 16 17 OSSL_NAMEMAP *ossl_namemap_new(void); 18 void ossl_namemap_free(OSSL_NAMEMAP *namemap); 19 int ossl_namemap_empty(OSSL_NAMEMAP *namemap); 20 21 int ossl_namemap_add_name(OSSL_NAMEMAP *namemap, int number, const char *name); 22 int ossl_namemap_add_name_n(OSSL_NAMEMAP *namemap, int number, 23 const char *name, size_t name_len); 24 25 int ossl_namemap_name2num(const OSSL_NAMEMAP *namemap, const char *name); 26 int ossl_namemap_name2num_n(const OSSL_NAMEMAP *namemap, 27 const char *name, size_t name_len); 28 int ossl_namemap_doall_names(const OSSL_NAMEMAP *namemap, int number, 29 void (*fn)(const char *name, void *data), 30 void *data); 31 32 int ossl_namemap_add_names(OSSL_NAMEMAP *namemap, int number, 33 const char *names, const char separator); 34 35=head1 DESCRIPTION 36 37A B<OSSL_NAMEMAP> is a one-to-many number E<lt>-E<gt> names map, which 38can be used to give any arbitrary set of names (any string) a unique 39dynamic identity that is valid throughout the lifetime of the associated 40library context. 41 42ossl_namemap_new() and ossl_namemap_free() construct and destruct a 43new B<OSSL_NAMEMAP>. 44This is suitable to use when the B<OSSL_NAMEMAP> is embedded in other 45structures, or should be independent for any reason. 46 47ossl_namemap_empty() checks if the given B<OSSL_NAMEMAP> is empty or 48not. 49 50ossl_namemap_stored() finds or auto-creates the default namemap in the 51given library context. 52The returned B<OSSL_NAMEMAP> can't be destructed using 53ossl_namemap_free(). 54 55ossl_namemap_add_name() adds a new name to the namemap if it's not already 56present. 57If the given I<number> is zero, a new number will be allocated to 58identify this I<name>. 59If the given I<number> is nonzero, the I<name> is added to the set of 60names already associated with that number. 61 62ossl_namemap_name2num() finds the number corresponding to the given 63I<name>. 64 65ossl_namemap_add_name_n() and ossl_namemap_name2num_n() do the same thing 66as ossl_namemap_add_name() and ossl_namemap_name2num(), but take a string 67length I<name_len> as well, allowing the caller to use a fragment of 68a string as a name. 69 70ossl_namemap_doall_names() walks through all names associated with 71I<number> in the given I<namemap> and calls the function I<fn> for 72each of them. 73I<fn> is also passed the I<data> argument, which allows any caller to 74pass extra data for that function to use. 75 76ossl_namemap_add_names() divides up a set of names given in I<names>, 77separated by I<separator>, and adds each to the I<namemap>, all with 78the same number. If some of them already exist in the I<namemap>, 79they must all have the same associated number, which will be adopted 80for any name that doesn't exist yet. 81 82=head1 RETURN VALUES 83 84ossl_namemap_new() and ossl_namemap_stored() return the pointer to a 85B<OSSL_NAMEMAP>, or NULL on error. 86 87ossl_namemap_empty() returns 1 if the B<OSSL_NAMEMAP> is NULL or 88empty, 0 if it's not empty, or -1 on internal error (such as inability 89to lock). 90 91ossl_namemap_add_name() and ossl_namemap_add_name_n() return the number 92associated with the added string, or zero on error. 93 94ossl_namemap_num2names() returns a pointer to a NULL-terminated list of 95pointers to the names corresponding to the given number, or NULL if 96it's undefined in the given B<OSSL_NAMEMAP>. 97 98ossl_namemap_name2num() and ossl_namemap_name2num_n() return the number 99corresponding to the given name, or 0 if it's undefined in the given 100B<OSSL_NAMEMAP>. 101 102ossl_namemap_doall_names() returns 1 if the callback was called for all names. A 103return value of 0 means that the callback was not called for any names. 104 105ossl_namemap_add_names() returns the number associated with the added 106names, or zero on error. 107 108=head1 NOTES 109 110The result from ossl_namemap_num2names() isn't thread safe, other threads 111dealing with the same namemap may cause the list of names to change 112location. 113It is therefore strongly recommended to only use the result in code 114guarded by a thread lock. 115 116=head1 HISTORY 117 118The functions described here were all added in OpenSSL 3.0. 119 120=head1 COPYRIGHT 121 122Copyright 2019-2021 The OpenSSL Project Authors. All Rights Reserved. 123 124Licensed under the Apache License 2.0 (the "License"). You may not use 125this file except in compliance with the License. You can obtain a copy 126in the file LICENSE in the source distribution or at 127L<https://www.openssl.org/source/license.html>. 128 129=cut 130