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