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_names, 7ossl_namemap_name2num, ossl_namemap_name2num_n, ossl_namemap_num2name, 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 23 int ossl_namemap_name2num(const OSSL_NAMEMAP *namemap, const char *name); 24 int ossl_namemap_name2num_n(const OSSL_NAMEMAP *namemap, 25 const char *name, size_t name_len); 26 const char *ossl_namemap_num2name(const OSSL_NAMEMAP *namemap, int number, 27 int idx); 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_name2num_n() does the same thing as 66ossl_namemap_name2num(), but takes a string length I<name_len> as well, 67allowing the caller to use a fragment of a string as a name. 68 69ossl_namemap_num2name() finds the I<idx>th name associated with the 70id I<number>. 71 72ossl_namemap_doall_names() walks through all names associated with 73I<number> in the given I<namemap> and calls the function I<fn> for 74each of them. 75I<fn> is also passed the I<data> argument, which allows any caller to 76pass extra data for that function to use. 77 78ossl_namemap_add_names() divides up a set of names given in I<names>, 79separated by I<separator>, and adds each to the I<namemap>, all with 80the same number. If some of them already exist in the I<namemap>, 81they must all have the same associated number, which will be adopted 82for any name that doesn't exist yet. 83 84=head1 RETURN VALUES 85 86ossl_namemap_new() and ossl_namemap_stored() return the pointer to a 87B<OSSL_NAMEMAP>, or NULL on error. 88 89ossl_namemap_empty() returns 1 if the B<OSSL_NAMEMAP> is NULL or 90empty, 0 if it's not empty, or -1 on internal error (such as inability 91to lock). 92 93ossl_namemap_add_name() returns the number associated with the added 94string, or zero on error. 95 96ossl_namemap_num2name() returns a pointer to I<idx>th name associated 97with id I<number>, or NULL if it's undefined in the given 98B<OSSL_NAMEMAP>. 99 100ossl_namemap_name2num() and ossl_namemap_name2num_n() return the number 101corresponding to the given name, or 0 if it's undefined in the given 102B<OSSL_NAMEMAP>. 103 104ossl_namemap_doall_names() returns 1 if the callback was called for all names. A 105return value of 0 means that the callback was not called for any names. 106 107ossl_namemap_add_names() returns the number associated with the added 108names, or zero on error. 109 110=head1 NOTES 111 112The result from ossl_namemap_num2names() isn't thread safe, other threads 113dealing with the same namemap may cause the list of names to change 114location. 115It is therefore strongly recommended to only use the result in code 116guarded by a thread lock. 117 118=head1 HISTORY 119 120The functions described here were all added in OpenSSL 3.0. 121 122=head1 COPYRIGHT 123 124Copyright 2019-2025 The OpenSSL Project Authors. All Rights Reserved. 125 126Licensed under the Apache License 2.0 (the "License"). You may not use 127this file except in compliance with the License. You can obtain a copy 128in the file LICENSE in the source distribution or at 129L<https://www.openssl.org/source/license.html>. 130 131=cut 132