]>
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 | ||
b97fdb57 RL |
17 | =for comment generic |
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. | |
64 | In the description here, I<TYPE> is used | |
739a1eb1 RS |
65 | as a placeholder for any of the OpenSSL datatypes, such as I<X509>. |
66 | ||
91da5e77 RS |
67 | STACK_OF() returns the name for a stack of the specified B<TYPE>. |
68 | DEFINE_STACK_OF() creates set of functions for a stack of B<TYPE>. This | |
739a1eb1 RS |
69 | will mean that type B<TYPE> is stored in each stack, the type is referenced by |
70 | STACK_OF(TYPE) and each function name begins with I<sk_TYPE_>. For example: | |
71 | ||
72 | TYPE *sk_TYPE_value(STACK_OF(TYPE) *sk, int idx); | |
73 | ||
91da5e77 | 74 | DEFINE_STACK_OF_CONST() is identical to DEFINE_STACK_OF() except |
739a1eb1 RS |
75 | each element is constant. For example: |
76 | ||
77 | const TYPE *sk_TYPE_value(STACK_OF(TYPE) *sk, int idx); | |
78 | ||
91da5e77 | 79 | DEFINE_SPECIAL_STACK_OF() defines a stack of B<TYPE> but |
739a1eb1 RS |
80 | each function uses B<FUNCNAME> in the function name. For example: |
81 | ||
82 | TYPE *sk_FUNCNAME_value(STACK_OF(TYPE) *sk, int idx); | |
83 | ||
91da5e77 RS |
84 | DEFINE_SPECIAL_STACK_OF_CONST() is similar except that each element is |
85 | constant: | |
86 | ||
87 | const TYPE *sk_FUNCNAME_value(STACK_OF(TYPE) *sk, int idx); | |
88 | ||
739a1eb1 RS |
89 | sk_TYPE_num() returns the number of elements in B<sk> or -1 if B<sk> is |
90 | B<NULL>. | |
91 | ||
92 | sk_TYPE_value() returns element B<idx> in B<sk>, where B<idx> starts at | |
93 | zero. If B<idx> is out of range then B<NULL> is returned. | |
94 | ||
d9c989fe PY |
95 | sk_TYPE_new() allocates a new empty stack using comparison function B<compare>. |
96 | If B<compare> is B<NULL> then no comparison function is used. This function is | |
3ceab379 | 97 | equivalent to sk_TYPE_new_reserve(compare, 0). |
739a1eb1 | 98 | |
3ceab379 PY |
99 | sk_TYPE_new_null() allocates a new empty stack with no comparison function. This |
100 | function is equivalent to sk_TYPE_new_reserve(NULL, 0). | |
739a1eb1 | 101 | |
1b3e2bbf P |
102 | sk_TYPE_reserve() allocates additional memory in the B<sk> structure |
103 | such that the next B<n> calls to sk_TYPE_insert(), sk_TYPE_push() | |
104 | or sk_TYPE_unshift() will not fail or cause memory to be allocated | |
105 | or reallocated. If B<n> is zero, any excess space allocated in the | |
106 | B<sk> structure is freed. On error B<sk> is unchanged. | |
107 | ||
3ceab379 PY |
108 | sk_TYPE_new_reserve() allocates a new stack. The new stack will have additional |
109 | memory allocated to hold B<n> elements if B<n> is positive. The next B<n> calls | |
110 | to sk_TYPE_insert(), sk_TYPE_push() or sk_TYPE_unshift() will not fail or cause | |
111 | memory to be allocated or reallocated. If B<n> is zero or less than zero, no | |
689c1788 | 112 | memory is allocated. sk_TYPE_new_reserve() also sets the comparison function |
3ceab379 PY |
113 | B<compare> to the newly created stack. If B<compare> is B<NULL> then no |
114 | comparison function is used. | |
115 | ||
d9c989fe | 116 | sk_TYPE_set_cmp_func() sets the comparison function of B<sk> to B<compare>. |
739a1eb1 RS |
117 | The previous comparison function is returned or B<NULL> if there was |
118 | no previous comparison function. | |
119 | ||
120 | sk_TYPE_free() frees up the B<sk> structure. It does B<not> free up any | |
121 | elements of B<sk>. After this call B<sk> is no longer valid. | |
122 | ||
123 | sk_TYPE_zero() sets the number of elements in B<sk> to zero. It does not free | |
124 | B<sk> so after this call B<sk> is still valid. | |
125 | ||
126 | sk_TYPE_pop_free() frees up all elements of B<sk> and B<sk> itself. The | |
127 | free function freefunc() is called on each element to free it. | |
128 | ||
129 | sk_TYPE_delete() deletes element B<i> from B<sk>. It returns the deleted | |
130 | element or B<NULL> if B<i> is out of range. | |
131 | ||
132 | sk_TYPE_delete_ptr() deletes element matching B<ptr> from B<sk>. It returns | |
133 | the deleted element or B<NULL> if no element matching B<ptr> was found. | |
134 | ||
135 | sk_TYPE_insert() inserts B<ptr> into B<sk> at position B<idx>. Any existing | |
136 | elements at or after B<idx> are moved downwards. If B<idx> is out of range | |
137 | the new element is appended to B<sk>. sk_TYPE_insert() either returns the | |
138 | number of elements in B<sk> after the new element is inserted or zero if | |
139 | an error (such as memory allocation failure) occurred. | |
140 | ||
141 | sk_TYPE_push() appends B<ptr> to B<sk> it is equivalent to: | |
142 | ||
143 | sk_TYPE_insert(sk, ptr, -1); | |
144 | ||
145 | sk_TYPE_unshift() inserts B<ptr> at the start of B<sk> it is equivalent to: | |
146 | ||
147 | sk_TYPE_insert(sk, ptr, 0); | |
148 | ||
149 | sk_TYPE_pop() returns and removes the last element from B<sk>. | |
150 | ||
151 | sk_TYPE_shift() returns and removes the first element from B<sk>. | |
152 | ||
153 | sk_TYPE_set() sets element B<idx> of B<sk> to B<ptr> replacing the current | |
154 | element. The new element value is returned or B<NULL> if an error occurred: | |
155 | this will only happen if B<sk> is B<NULL> or B<idx> is out of range. | |
156 | ||
89b06ca7 P |
157 | sk_TYPE_find() searches B<sk> for the element B<ptr>. In the case |
158 | where no comparison function has been specified, the function performs | |
159 | a linear search for a pointer equal to B<ptr>. The index of the first | |
160 | matching element is returned or B<-1> if there is no match. In the case | |
161 | where a comparison function has been specified, B<sk> is sorted then | |
162 | sk_TYPE_find() returns the index of a matching element or B<-1> if there | |
163 | is no match. Note that, in this case, the matching element returned is | |
164 | not guaranteed to be the first; the comparison function will usually | |
165 | compare the values pointed to rather than the pointers themselves and | |
166 | the order of elements in B<sk> could change. | |
167 | ||
168 | sk_TYPE_find_ex() operates like sk_TYPE_find() except when a comparison | |
169 | function has been specified and no matching element is found. Instead | |
170 | of returning B<-1>, sk_TYPE_find_ex() returns the index of the element | |
171 | either before or after the location where B<ptr> would be if it were | |
172 | present in B<sk>. | |
739a1eb1 RS |
173 | |
174 | sk_TYPE_sort() sorts B<sk> using the supplied comparison function. | |
175 | ||
176 | sk_TYPE_is_sorted() returns B<1> if B<sk> is sorted and B<0> otherwise. | |
177 | ||
178 | sk_TYPE_dup() returns a copy of B<sk>. Note the pointers in the copy | |
179 | are identical to the original. | |
180 | ||
181 | sk_TYPE_deep_copy() returns a new stack where each element has been copied. | |
182 | Copying is performed by the supplied copyfunc() and freeing by freefunc(). The | |
183 | function freefunc() is only called if an error occurs. | |
184 | ||
185 | =head1 NOTES | |
186 | ||
187 | Care should be taken when accessing stacks in multi-threaded environments. | |
188 | Any operation which increases the size of a stack such as sk_TYPE_insert() or | |
189 | sk_push() can "grow" the size of an internal array and cause race conditions | |
190 | if the same stack is accessed in a different thread. Operations such as | |
191 | sk_find() and sk_sort() can also reorder the stack. | |
192 | ||
193 | Any comparison function supplied should use a metric suitable | |
194 | for use in a binary search operation. That is it should return zero, a | |
195 | positive or negative value if B<a> is equal to, greater than | |
196 | or less than B<b> respectively. | |
197 | ||
198 | Care should be taken when checking the return values of the functions | |
199 | sk_TYPE_find() and sk_TYPE_find_ex(). They return an index to the | |
200 | matching element. In particular B<0> indicates a matching first element. | |
201 | A failed search is indicated by a B<-1> return value. | |
202 | ||
91da5e77 RS |
203 | STACK_OF(), DEFINE_STACK_OF(), DEFINE_STACK_OF_CONST(), and |
204 | DEFINE_SPECIAL_STACK_OF() are implemented as macros. | |
205 | ||
1f5e0f92 P |
206 | The underlying utility B<OPENSSL_sk_> API should not be used directly. |
207 | It defines these functions: OPENSSL_sk_deep_copy(), | |
208 | OPENSSL_sk_delete(), OPENSSL_sk_delete_ptr(), OPENSSL_sk_dup(), | |
209 | OPENSSL_sk_find(), OPENSSL_sk_find_ex(), OPENSSL_sk_free(), | |
210 | OPENSSL_sk_insert(), OPENSSL_sk_is_sorted(), OPENSSL_sk_new(), | |
211 | OPENSSL_sk_new_null(), OPENSSL_sk_num(), OPENSSL_sk_pop(), | |
212 | OPENSSL_sk_pop_free(), OPENSSL_sk_push(), OPENSSL_sk_reserve(), | |
213 | OPENSSL_sk_set(), OPENSSL_sk_set_cmp_func(), OPENSSL_sk_shift(), | |
214 | OPENSSL_sk_sort(), OPENSSL_sk_unshift(), OPENSSL_sk_value(), | |
215 | OPENSSL_sk_zero(). | |
216 | ||
739a1eb1 RS |
217 | =head1 RETURN VALUES |
218 | ||
219 | sk_TYPE_num() returns the number of elements in the stack or B<-1> if the | |
220 | passed stack is B<NULL>. | |
221 | ||
222 | sk_TYPE_value() returns a pointer to a stack element or B<NULL> if the | |
223 | index is out of range. | |
224 | ||
3ceab379 PY |
225 | sk_TYPE_new(), sk_TYPE_new_null() and sk_TYPE_new_reserve() return an empty |
226 | stack or B<NULL> if an error occurs. | |
739a1eb1 | 227 | |
1b3e2bbf P |
228 | sk_TYPE_reserve() returns B<1> on successful allocation of the required memory |
229 | or B<0> on error. | |
230 | ||
739a1eb1 RS |
231 | sk_TYPE_set_cmp_func() returns the old comparison function or B<NULL> if |
232 | there was no old comparison function. | |
233 | ||
234 | sk_TYPE_free(), sk_TYPE_zero(), sk_TYPE_pop_free() and sk_TYPE_sort() do | |
235 | not return values. | |
236 | ||
237 | sk_TYPE_pop(), sk_TYPE_shift(), sk_TYPE_delete() and sk_TYPE_delete_ptr() | |
238 | return a pointer to the deleted element or B<NULL> on error. | |
239 | ||
240 | sk_TYPE_insert(), sk_TYPE_push() and sk_TYPE_unshift() return the total | |
241 | number of elements in the stack and 0 if an error occurred. | |
242 | ||
243 | sk_TYPE_set() returns a pointer to the replacement element or B<NULL> on | |
244 | error. | |
245 | ||
246 | sk_TYPE_find() and sk_TYPE_find_ex() return an index to the found element | |
247 | or B<-1> on error. | |
248 | ||
249 | sk_TYPE_is_sorted() returns B<1> if the stack is sorted and B<0> if it is | |
250 | not. | |
251 | ||
252 | sk_TYPE_dup() and sk_TYPE_deep_copy() return a pointer to the copy of the | |
253 | stack. | |
254 | ||
255 | =head1 HISTORY | |
256 | ||
257 | Before OpenSSL 1.1.0, this was implemented via macros and not inline functions | |
258 | and was not a public API. | |
259 | ||
689c1788 | 260 | sk_TYPE_reserve() and sk_TYPE_new_reserve() were added in OpenSSL 1.1.1. |
3ceab379 | 261 | |
739a1eb1 RS |
262 | =head1 COPYRIGHT |
263 | ||
1b3e2bbf | 264 | Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved. |
739a1eb1 | 265 | |
4746f25a | 266 | Licensed under the Apache License 2.0 (the "License"). You may not use |
739a1eb1 RS |
267 | this file except in compliance with the License. You can obtain a copy |
268 | in the file LICENSE in the source distribution or at | |
269 | L<https://www.openssl.org/source/license.html>. | |
270 | ||
271 | =cut |