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