]>
Commit | Line | Data |
---|---|---|
f2182a4e RL |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
5 | ossl_namemap_new, ossl_namemap_free, ossl_namemap_stored, | |
651d4418 | 6 | ossl_namemap_add, ossl_namemap_name2num, ossl_namemap_doall_names |
f2182a4e RL |
7 | - internal number E<lt>-E<gt> name map |
8 | ||
9 | =head1 SYNOPSIS | |
10 | ||
11 | #include "internal/cryptlib.h" | |
12 | ||
13 | OSSL_NAMEMAP *ossl_namemap_stored(OPENSSL_CTX *libctx); | |
14 | ||
15 | OSSL_NAMEMAP *ossl_namemap_new(void); | |
16 | void ossl_namemap_free(OSSL_NAMEMAP *namemap); | |
17 | ||
651d4418 RL |
18 | int ossl_namemap_add(OSSL_NAMEMAP *namemap, int number, const char *name); |
19 | ||
20 | int ossl_namemap_name2num(const OSSL_NAMEMAP *namemap, const char *name); | |
21 | void ossl_namemap_doall_names(const OSSL_NAMEMAP *namemap, int number, | |
22 | void (*fn)(const char *name, void *data), | |
23 | void *data); | |
f2182a4e RL |
24 | |
25 | =head1 DESCRIPTION | |
26 | ||
651d4418 RL |
27 | A B<OSSL_NAMEMAP> is a one-to-many number E<lt>-E<gt> names map, which |
28 | can be used to give any arbitrary set of names (any string) a unique | |
29 | dynamic identity that is valid throughout the lifetime of the associated | |
f2182a4e RL |
30 | library context. |
31 | ||
32 | ossl_namemap_new() and ossl_namemap_free() construct and destruct a | |
33 | new B<OSSL_NAMEMAP>. | |
34 | This is suitable to use when the B<OSSL_NAMEMAP> is embedded in other | |
35 | structures, or should be independent for any reason. | |
36 | ||
37 | ossl_namemap_stored() finds or auto-creates the default namemap in the | |
38 | given library context. | |
39 | The returned B<OSSL_NAMEMAP> can't be destructed using | |
40 | ossl_namemap_free(). | |
41 | ||
42 | ossl_namemap_add() adds a new name to the namemap if it's not already | |
43 | present. | |
651d4418 RL |
44 | If the given I<number> is zero, a new number will be allocated to |
45 | identify this I<name>. | |
46 | If the given I<number> is non-zero, the I<name> is added to the set of | |
47 | names already associated with that number. | |
f2182a4e | 48 | |
651d4418 RL |
49 | ossl_namemap_name2num() finds the number corresponding to the given |
50 | I<name>. | |
f2182a4e | 51 | |
651d4418 RL |
52 | ossl_namemap_doall_names() walks through all names associated with |
53 | I<number> in the given I<namemap> and calls the function I<fn> for | |
54 | each of them. | |
55 | I<fn> is also passed the I<data> argument, which allows any caller to | |
56 | pass extra data for that function to use. | |
f2182a4e RL |
57 | |
58 | =head1 RETURN VALUES | |
59 | ||
60 | ossl_namemap_new() and ossl_namemap_stored() return the pointer to a | |
61 | B<OSSL_NAMEMAP>, or NULL on error. | |
62 | ||
63 | ossl_namemap_add() returns the number associated with the added | |
64 | string, or zero on error. | |
65 | ||
651d4418 RL |
66 | ossl_namemap_num2names() returns a pointer to a NULL-terminated list of |
67 | pointers to the names corresponding to the given number, or NULL if | |
68 | it's undefined in the given B<OSSL_NAMEMAP>. | |
f2182a4e | 69 | |
651d4418 | 70 | ossl_namemap_name2num() returns the number corresponding to the given |
f2182a4e RL |
71 | name, or 0 if it's undefined in the given B<OSSL_NAMEMAP>. |
72 | ||
651d4418 RL |
73 | =head1 NOTES |
74 | ||
75 | The result from ossl_namemap_num2names() isn't thread safe, other threads | |
76 | dealing with the same namemap may cause the list of names to change | |
77 | location. | |
78 | It is therefore strongly recommended to only use the result in code | |
79 | guarded by a thread lock. | |
80 | ||
f2182a4e RL |
81 | =head1 HISTORY |
82 | ||
83 | The functions described here were all added in OpenSSL 3.0. | |
84 | ||
85 | =head1 COPYRIGHT | |
86 | ||
87 | Copyright 2019 The OpenSSL Project Authors. All Rights Reserved. | |
88 | ||
89 | Licensed under the Apache License 2.0 (the "License"). You may not use | |
90 | this file except in compliance with the License. You can obtain a copy | |
91 | in the file LICENSE in the source distribution or at | |
92 | L<https://www.openssl.org/source/license.html>. | |
93 | ||
94 | =cut |