]>
Commit | Line | Data |
---|---|---|
739a1eb1 RS |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
5 | DEFINE_STACK_OF, DEFINE_STACK_OF_CONST, DEFINE_SPECIAL_STACK_OF, | |
91da5e77 | 6 | DEFINE_SPECIAL_STACK_OF_CONST, |
1b3e2bbf P |
7 | sk_TYPE_num, sk_TYPE_value, sk_TYPE_new, sk_TYPE_new_null, |
8 | sk_TYPE_reserve, sk_TYPE_free, sk_TYPE_zero, sk_TYPE_delete, | |
9 | sk_TYPE_delete_ptr, sk_TYPE_push, sk_TYPE_unshift, sk_TYPE_pop, | |
10 | sk_TYPE_shift, sk_TYPE_pop_free, sk_TYPE_insert, sk_TYPE_set, | |
11 | sk_TYPE_find, sk_TYPE_find_ex, sk_TYPE_sort, sk_TYPE_is_sorted, | |
3ceab379 PY |
12 | sk_TYPE_dup, sk_TYPE_deep_copy, sk_TYPE_set_cmp_func, sk_TYPE_new_reserve |
13 | - stack container | |
739a1eb1 RS |
14 | |
15 | =head1 SYNOPSIS | |
16 | ||
bb82531f | 17 | =for openssl generic |
b97fdb57 | 18 | |
739a1eb1 RS |
19 | #include <openssl/safestack.h> |
20 | ||
91da5e77 RS |
21 | STACK_OF(TYPE) |
22 | DEFINE_STACK_OF(TYPE) | |
23 | DEFINE_STACK_OF_CONST(TYPE) | |
24 | DEFINE_SPECIAL_STACK_OF(FUNCTYPE, TYPE) | |
25 | DEFINE_SPECIAL_STACK_OF_CONST(FUNCTYPE, TYPE) | |
739a1eb1 RS |
26 | |
27 | typedef int (*sk_TYPE_compfunc)(const TYPE *const *a, const TYPE *const *b); | |
28 | typedef TYPE * (*sk_TYPE_copyfunc)(const TYPE *a); | |
29 | typedef void (*sk_TYPE_freefunc)(TYPE *a); | |
30 | ||
31 | int sk_TYPE_num(const STACK_OF(TYPE) *sk); | |
32 | TYPE *sk_TYPE_value(const STACK_OF(TYPE) *sk, int idx); | |
33 | STACK_OF(TYPE) *sk_TYPE_new(sk_TYPE_compfunc compare); | |
34 | STACK_OF(TYPE) *sk_TYPE_new_null(void); | |
62f45e34 | 35 | int sk_TYPE_reserve(STACK_OF(TYPE) *sk, int n); |
739a1eb1 RS |
36 | void sk_TYPE_free(const STACK_OF(TYPE) *sk); |
37 | void sk_TYPE_zero(const STACK_OF(TYPE) *sk); | |
38 | TYPE *sk_TYPE_delete(STACK_OF(TYPE) *sk, int i); | |
39 | TYPE *sk_TYPE_delete_ptr(STACK_OF(TYPE) *sk, TYPE *ptr); | |
36639907 RS |
40 | int sk_TYPE_push(STACK_OF(TYPE) *sk, const TYPE *ptr); |
41 | int sk_TYPE_unshift(STACK_OF(TYPE) *sk, const TYPE *ptr); | |
739a1eb1 RS |
42 | TYPE *sk_TYPE_pop(STACK_OF(TYPE) *sk); |
43 | TYPE *sk_TYPE_shift(STACK_OF(TYPE) *sk); | |
44 | void sk_TYPE_pop_free(STACK_OF(TYPE) *sk, sk_TYPE_freefunc freefunc); | |
45 | int sk_TYPE_insert(STACK_OF(TYPE) *sk, TYPE *ptr, int idx); | |
36639907 | 46 | TYPE *sk_TYPE_set(STACK_OF(TYPE) *sk, int idx, const TYPE *ptr); |
739a1eb1 RS |
47 | int sk_TYPE_find(STACK_OF(TYPE) *sk, TYPE *ptr); |
48 | int sk_TYPE_find_ex(STACK_OF(TYPE) *sk, TYPE *ptr); | |
49 | void sk_TYPE_sort(const STACK_OF(TYPE) *sk); | |
50 | int sk_TYPE_is_sorted(const STACK_OF(TYPE) *sk); | |
c0c9c0c0 F |
51 | STACK_OF(TYPE) *sk_TYPE_dup(const STACK_OF(TYPE) *sk); |
52 | STACK_OF(TYPE) *sk_TYPE_deep_copy(const STACK_OF(TYPE) *sk, | |
739a1eb1 RS |
53 | sk_TYPE_copyfunc copyfunc, |
54 | sk_TYPE_freefunc freefunc); | |
e9b77246 BB |
55 | sk_TYPE_compfunc (*sk_TYPE_set_cmp_func(STACK_OF(TYPE) *sk, |
56 | sk_TYPE_compfunc compare)); | |
3ceab379 | 57 | STACK_OF(TYPE) *sk_TYPE_new_reserve(sk_TYPE_compfunc compare, int n); |
739a1eb1 RS |
58 | |
59 | =head1 DESCRIPTION | |
60 | ||
61 | Applications can create and use their own stacks by placing any of the macros | |
c952780c RS |
62 | described below in a header file. These macros define typesafe inline |
63 | functions that wrap around the utility B<OPENSSL_sk_> API. | |
bbecf04e RL |
64 | In the description here, B<I<TYPE>> is used |
65 | as a placeholder for any of the OpenSSL datatypes, such as B<X509>. | |
739a1eb1 | 66 | |
852c2ed2 RS |
67 | The STACK_OF() macro returns the name for a stack of the specified B<I<TYPE>>. |
68 | This is an opaque pointer to a structure declaration. | |
69 | This can be used in every header file that references the stack. | |
70 | There are several B<DEFINE...> macros that create static inline functions | |
71 | for all of the functions described on this page. | |
72 | This should normally be used in one source file, and the stack manipulation | |
73 | is wrapped with application-specific functions. | |
74 | ||
75 | DEFINE_STACK_OF() creates set of functions for a stack of B<I<TYPE>> elements. | |
76 | The type is referenced by | |
bbecf04e | 77 | B<STACK_OF>(B<I<TYPE>>) and each function name begins with B<sk_I<TYPE>_>. |
91da5e77 | 78 | DEFINE_STACK_OF_CONST() is identical to DEFINE_STACK_OF() except |
852c2ed2 | 79 | each element is constant. |
739a1eb1 | 80 | |
852c2ed2 RS |
81 | /* DEFINE_STACK_OF(TYPE) */ |
82 | TYPE *sk_TYPE_value(STACK_OF(TYPE) *sk, int idx); | |
83 | /* DEFINE_STACK_OF_CONST(TYPE) */ | |
739a1eb1 RS |
84 | const TYPE *sk_TYPE_value(STACK_OF(TYPE) *sk, int idx); |
85 | ||
852c2ed2 RS |
86 | DEFINE_SPECIAL_STACK_OF() and DEFINE_SPECIAL_STACK_OF_CONST() are similar |
87 | except B<FUNCNAME> is used in the function names: | |
739a1eb1 | 88 | |
852c2ed2 | 89 | /* DEFINE_SPECIAL_STACK_OF(TYPE, FUNCNAME) */ |
739a1eb1 | 90 | TYPE *sk_FUNCNAME_value(STACK_OF(TYPE) *sk, int idx); |
852c2ed2 | 91 | /* DEFINE_SPECIAL_STACK_OF(TYPE, FUNCNAME) */ |
91da5e77 RS |
92 | const TYPE *sk_FUNCNAME_value(STACK_OF(TYPE) *sk, int idx); |
93 | ||
bbecf04e RL |
94 | B<sk_I<TYPE>_num>() returns the number of elements in I<sk> or -1 if I<sk> is |
95 | NULL. | |
739a1eb1 | 96 | |
bbecf04e RL |
97 | B<sk_I<TYPE>_value>() returns element I<idx> in I<sk>, where I<idx> starts at |
98 | zero. If I<idx> is out of range then NULL is returned. | |
739a1eb1 | 99 | |
bbecf04e RL |
100 | B<sk_I<TYPE>_new>() allocates a new empty stack using comparison function |
101 | I<compare>. If I<compare> is NULL then no comparison function is used. This | |
102 | function is equivalent to B<sk_I<TYPE>_new_reserve>(I<compare>, 0). | |
739a1eb1 | 103 | |
bbecf04e RL |
104 | B<sk_I<TYPE>_new_null>() allocates a new empty stack with no comparison |
105 | function. This function is equivalent to B<sk_I<TYPE>_new_reserve>(NULL, 0). | |
739a1eb1 | 106 | |
bbecf04e RL |
107 | B<sk_I<TYPE>_reserve>() allocates additional memory in the I<sk> structure |
108 | such that the next I<n> calls to B<sk_I<TYPE>_insert>(), B<sk_I<TYPE>_push>() | |
109 | or B<sk_I<TYPE>_unshift>() will not fail or cause memory to be allocated | |
110 | or reallocated. If I<n> is zero, any excess space allocated in the | |
111 | I<sk> structure is freed. On error I<sk> is unchanged. | |
1b3e2bbf | 112 | |
bbecf04e RL |
113 | B<sk_I<TYPE>_new_reserve>() allocates a new stack. The new stack will have |
114 | additional memory allocated to hold I<n> elements if I<n> is positive. | |
115 | The next I<n> calls to B<sk_I<TYPE>_insert>(), B<sk_I<TYPE>_push>() or | |
116 | B<sk_I<TYPE>_unshift>() will not fail or cause memory to be allocated or | |
117 | reallocated. If I<n> is zero or less than zero, no memory is allocated. | |
118 | B<sk_I<TYPE>_new_reserve>() also sets the comparison function I<compare> | |
119 | to the newly created stack. If I<compare> is NULL then no comparison | |
120 | function is used. | |
3ceab379 | 121 | |
bbecf04e RL |
122 | B<sk_I<TYPE>_set_cmp_func>() sets the comparison function of I<sk> to |
123 | I<compare>. The previous comparison function is returned or NULL if there | |
124 | was no previous comparison function. | |
739a1eb1 | 125 | |
bbecf04e RL |
126 | B<sk_I<TYPE>_free>() frees up the I<sk> structure. It does I<not> free up any |
127 | elements of I<sk>. After this call I<sk> is no longer valid. | |
739a1eb1 | 128 | |
bbecf04e RL |
129 | B<sk_I<TYPE>_zero>() sets the number of elements in I<sk> to zero. It does not |
130 | free I<sk> so after this call I<sk> is still valid. | |
739a1eb1 | 131 | |
bbecf04e | 132 | B<sk_I<TYPE>_pop_free>() frees up all elements of I<sk> and I<sk> itself. The |
739a1eb1 RS |
133 | free function freefunc() is called on each element to free it. |
134 | ||
bbecf04e RL |
135 | B<sk_I<TYPE>_delete>() deletes element I<i> from I<sk>. It returns the deleted |
136 | element or NULL if I<i> is out of range. | |
739a1eb1 | 137 | |
bbecf04e RL |
138 | B<sk_I<TYPE>_delete_ptr>() deletes element matching I<ptr> from I<sk>. It |
139 | returns the deleted element or NULL if no element matching I<ptr> was found. | |
739a1eb1 | 140 | |
bbecf04e RL |
141 | B<sk_I<TYPE>_insert>() inserts I<ptr> into I<sk> at position I<idx>. Any |
142 | existing elements at or after I<idx> are moved downwards. If I<idx> is out | |
143 | of range the new element is appended to I<sk>. B<sk_I<TYPE>_insert>() either | |
144 | returns the number of elements in I<sk> after the new element is inserted or | |
145 | zero if an error (such as memory allocation failure) occurred. | |
739a1eb1 | 146 | |
bbecf04e | 147 | B<sk_I<TYPE>_push>() appends I<ptr> to I<sk> it is equivalent to: |
739a1eb1 RS |
148 | |
149 | sk_TYPE_insert(sk, ptr, -1); | |
150 | ||
bbecf04e RL |
151 | B<sk_I<TYPE>_unshift>() inserts I<ptr> at the start of I<sk> it is equivalent |
152 | to: | |
739a1eb1 RS |
153 | |
154 | sk_TYPE_insert(sk, ptr, 0); | |
155 | ||
bbecf04e | 156 | B<sk_I<TYPE>_pop>() returns and removes the last element from I<sk>. |
739a1eb1 | 157 | |
bbecf04e | 158 | B<sk_I<TYPE>_shift>() returns and removes the first element from I<sk>. |
739a1eb1 | 159 | |
bbecf04e RL |
160 | B<sk_I<TYPE>_set>() sets element I<idx> of I<sk> to I<ptr> replacing the current |
161 | element. The new element value is returned or NULL if an error occurred: | |
162 | this will only happen if I<sk> is NULL or I<idx> is out of range. | |
739a1eb1 | 163 | |
bbecf04e | 164 | B<sk_I<TYPE>_find>() searches I<sk> for the element I<ptr>. In the case |
89b06ca7 | 165 | where no comparison function has been specified, the function performs |
bbecf04e | 166 | a linear search for a pointer equal to I<ptr>. The index of the first |
89b06ca7 | 167 | matching element is returned or B<-1> if there is no match. In the case |
bbecf04e RL |
168 | where a comparison function has been specified, I<sk> is sorted then |
169 | B<sk_I<TYPE>_find>() returns the index of a matching element or B<-1> if there | |
89b06ca7 P |
170 | is no match. Note that, in this case, the matching element returned is |
171 | not guaranteed to be the first; the comparison function will usually | |
172 | compare the values pointed to rather than the pointers themselves and | |
bbecf04e | 173 | the order of elements in I<sk> could change. |
89b06ca7 | 174 | |
bbecf04e RL |
175 | B<sk_I<TYPE>_find_ex>() operates like B<sk_I<TYPE>_find>() except when a |
176 | comparison function has been specified and no matching element is found. | |
177 | Instead of returning B<-1>, B<sk_I<TYPE>_find_ex>() returns the index of the | |
178 | element either before or after the location where I<ptr> would be if it were | |
179 | present in I<sk>. | |
739a1eb1 | 180 | |
bbecf04e | 181 | B<sk_I<TYPE>_sort>() sorts I<sk> using the supplied comparison function. |
739a1eb1 | 182 | |
bbecf04e | 183 | B<sk_I<TYPE>_is_sorted>() returns B<1> if I<sk> is sorted and B<0> otherwise. |
739a1eb1 | 184 | |
d53b437f DDO |
185 | B<sk_I<TYPE>_dup>() returns a shallow copy of I<sk> |
186 | or an empty stack if the passed stack is NULL. | |
187 | Note the pointers in the copy are identical to the original. | |
739a1eb1 | 188 | |
bbecf04e | 189 | B<sk_I<TYPE>_deep_copy>() returns a new stack where each element has been |
d53b437f DDO |
190 | copied or an empty stack if the passed stack is NULL. |
191 | Copying is performed by the supplied copyfunc() and freeing by freefunc(). | |
192 | The function freefunc() is only called if an error occurs. | |
739a1eb1 RS |
193 | |
194 | =head1 NOTES | |
195 | ||
196 | Care should be taken when accessing stacks in multi-threaded environments. | |
bbecf04e RL |
197 | Any operation which increases the size of a stack such as B<sk_I<TYPE>_insert>() |
198 | or B<sk_I<TYPE>_push>() can "grow" the size of an internal array and cause race | |
199 | conditions if the same stack is accessed in a different thread. Operations such | |
200 | as B<sk_I<TYPE>_find>() and B<sk_I<TYPE>_sort>() can also reorder the stack. | |
739a1eb1 RS |
201 | |
202 | Any comparison function supplied should use a metric suitable | |
203 | for use in a binary search operation. That is it should return zero, a | |
bbecf04e RL |
204 | positive or negative value if I<a> is equal to, greater than |
205 | or less than I<b> respectively. | |
739a1eb1 RS |
206 | |
207 | Care should be taken when checking the return values of the functions | |
bbecf04e | 208 | B<sk_I<TYPE>_find>() and B<sk_I<TYPE>_find_ex>(). They return an index to the |
739a1eb1 RS |
209 | matching element. In particular B<0> indicates a matching first element. |
210 | A failed search is indicated by a B<-1> return value. | |
211 | ||
91da5e77 RS |
212 | STACK_OF(), DEFINE_STACK_OF(), DEFINE_STACK_OF_CONST(), and |
213 | DEFINE_SPECIAL_STACK_OF() are implemented as macros. | |
214 | ||
1f5e0f92 P |
215 | The underlying utility B<OPENSSL_sk_> API should not be used directly. |
216 | It defines these functions: OPENSSL_sk_deep_copy(), | |
217 | OPENSSL_sk_delete(), OPENSSL_sk_delete_ptr(), OPENSSL_sk_dup(), | |
218 | OPENSSL_sk_find(), OPENSSL_sk_find_ex(), OPENSSL_sk_free(), | |
219 | OPENSSL_sk_insert(), OPENSSL_sk_is_sorted(), OPENSSL_sk_new(), | |
220 | OPENSSL_sk_new_null(), OPENSSL_sk_num(), OPENSSL_sk_pop(), | |
221 | OPENSSL_sk_pop_free(), OPENSSL_sk_push(), OPENSSL_sk_reserve(), | |
222 | OPENSSL_sk_set(), OPENSSL_sk_set_cmp_func(), OPENSSL_sk_shift(), | |
223 | OPENSSL_sk_sort(), OPENSSL_sk_unshift(), OPENSSL_sk_value(), | |
224 | OPENSSL_sk_zero(). | |
225 | ||
739a1eb1 RS |
226 | =head1 RETURN VALUES |
227 | ||
bbecf04e RL |
228 | B<sk_I<TYPE>_num>() returns the number of elements in the stack or B<-1> if the |
229 | passed stack is NULL. | |
739a1eb1 | 230 | |
bbecf04e | 231 | B<sk_I<TYPE>_value>() returns a pointer to a stack element or NULL if the |
739a1eb1 RS |
232 | index is out of range. |
233 | ||
bbecf04e RL |
234 | B<sk_I<TYPE>_new>(), B<sk_I<TYPE>_new_null>() and B<sk_I<TYPE>_new_reserve>() |
235 | return an empty stack or NULL if an error occurs. | |
739a1eb1 | 236 | |
bbecf04e RL |
237 | B<sk_I<TYPE>_reserve>() returns B<1> on successful allocation of the required |
238 | memory or B<0> on error. | |
1b3e2bbf | 239 | |
bbecf04e | 240 | B<sk_I<TYPE>_set_cmp_func>() returns the old comparison function or NULL if |
739a1eb1 RS |
241 | there was no old comparison function. |
242 | ||
bbecf04e RL |
243 | B<sk_I<TYPE>_free>(), B<sk_I<TYPE>_zero>(), B<sk_I<TYPE>_pop_free>() and |
244 | B<sk_I<TYPE>_sort>() do not return values. | |
739a1eb1 | 245 | |
bbecf04e RL |
246 | B<sk_I<TYPE>_pop>(), B<sk_I<TYPE>_shift>(), B<sk_I<TYPE>_delete>() and |
247 | B<sk_I<TYPE>_delete_ptr>() return a pointer to the deleted element or NULL | |
248 | on error. | |
739a1eb1 | 249 | |
bbecf04e RL |
250 | B<sk_I<TYPE>_insert>(), B<sk_I<TYPE>_push>() and B<sk_I<TYPE>_unshift>() return |
251 | the total number of elements in the stack and 0 if an error occurred. | |
739a1eb1 | 252 | |
bbecf04e | 253 | B<sk_I<TYPE>_set>() returns a pointer to the replacement element or NULL on |
739a1eb1 RS |
254 | error. |
255 | ||
bbecf04e RL |
256 | B<sk_I<TYPE>_find>() and B<sk_I<TYPE>_find_ex>() return an index to the found |
257 | element or B<-1> on error. | |
739a1eb1 | 258 | |
bbecf04e | 259 | B<sk_I<TYPE>_is_sorted>() returns B<1> if the stack is sorted and B<0> if it is |
739a1eb1 RS |
260 | not. |
261 | ||
bbecf04e | 262 | B<sk_I<TYPE>_dup>() and B<sk_I<TYPE>_deep_copy>() return a pointer to the copy |
d53b437f | 263 | of the stack or NULL on error. |
739a1eb1 RS |
264 | |
265 | =head1 HISTORY | |
266 | ||
267 | Before OpenSSL 1.1.0, this was implemented via macros and not inline functions | |
268 | and was not a public API. | |
269 | ||
bbecf04e RL |
270 | B<sk_I<TYPE>_reserve>() and B<sk_I<TYPE>_new_reserve>() were added in OpenSSL |
271 | 1.1.1. | |
3ceab379 | 272 | |
739a1eb1 RS |
273 | =head1 COPYRIGHT |
274 | ||
454afd98 | 275 | Copyright 2000-2020 The OpenSSL Project Authors. All Rights Reserved. |
739a1eb1 | 276 | |
4746f25a | 277 | Licensed under the Apache License 2.0 (the "License"). You may not use |
739a1eb1 RS |
278 | this file except in compliance with the License. You can obtain a copy |
279 | in the file LICENSE in the source distribution or at | |
280 | L<https://www.openssl.org/source/license.html>. | |
281 | ||
282 | =cut |