Debian Codegraph @

upstream/debian-unstable/man3/DEFINE_STACK_OF.3ssl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "DEFINE_STACK_OF 3SSL"
58 .TH DEFINE_STACK_OF 3SSL 2026-04-07 3.6.2 OpenSSL
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 DEFINE_STACK_OF, DEFINE_STACK_OF_CONST, DEFINE_SPECIAL_STACK_OF,
65 DEFINE_SPECIAL_STACK_OF_CONST,
66 sk_TYPE_num, sk_TYPE_value, sk_TYPE_new, sk_TYPE_new_null,
67 sk_TYPE_reserve, sk_TYPE_free, sk_TYPE_zero, sk_TYPE_delete,
68 sk_TYPE_delete_ptr, sk_TYPE_push, sk_TYPE_unshift, sk_TYPE_pop,
69 sk_TYPE_shift, sk_TYPE_pop_free, sk_TYPE_insert, sk_TYPE_set,
70 sk_TYPE_find, sk_TYPE_find_ex, sk_TYPE_find_all, sk_TYPE_sort,
71 sk_TYPE_is_sorted, sk_TYPE_dup, sk_TYPE_deep_copy, sk_TYPE_set_cmp_func,
72 sk_TYPE_new_reserve,
73 OPENSSL_sk_deep_copy, OPENSSL_sk_delete, OPENSSL_sk_delete_ptr,
74 OPENSSL_sk_dup, OPENSSL_sk_find, OPENSSL_sk_find_ex, OPENSSL_sk_find_all,
75 OPENSSL_sk_free, OPENSSL_sk_insert, OPENSSL_sk_is_sorted, OPENSSL_sk_new,
76 OPENSSL_sk_new_null, OPENSSL_sk_new_reserve, OPENSSL_sk_num, OPENSSL_sk_pop,
77 OPENSSL_sk_pop_free, OPENSSL_sk_push, OPENSSL_sk_reserve, OPENSSL_sk_set,
78 OPENSSL_sk_set_thunks, OPENSSL_sk_set_cmp_func, OPENSSL_sk_shift,
79 OPENSSL_sk_sort, OPENSSL_sk_unshift, OPENSSL_sk_value, OPENSSL_sk_zero
80 \&\- stack container
81 .SH SYNOPSIS
82 .IX Header "SYNOPSIS"
83 .Vb 1
84 \& #include <openssl/safestack.h>
85 \&
86 \& STACK_OF(TYPE)
87 \& DEFINE_STACK_OF(TYPE)
88 \& DEFINE_STACK_OF_CONST(TYPE)
89 \& DEFINE_SPECIAL_STACK_OF(FUNCTYPE, TYPE)
90 \& DEFINE_SPECIAL_STACK_OF_CONST(FUNCTYPE, TYPE)
91 \&
92 \& typedef int (*sk_TYPE_compfunc)(const TYPE *const *a, const TYPE *const *b);
93 \& typedef TYPE * (*sk_TYPE_copyfunc)(const TYPE *a);
94 \& typedef void (*sk_TYPE_freefunc)(TYPE *a);
95 \&
96 \& int sk_TYPE_num(const STACK_OF(TYPE) *sk);
97 \& TYPE *sk_TYPE_value(const STACK_OF(TYPE) *sk, int idx);
98 \& STACK_OF(TYPE) *sk_TYPE_new(sk_TYPE_compfunc compare);
99 \& STACK_OF(TYPE) *sk_TYPE_new_null(void);
100 \& int sk_TYPE_reserve(STACK_OF(TYPE) *sk, int n);
101 \& void sk_TYPE_free(STACK_OF(TYPE) *sk);
102 \& void sk_TYPE_zero(STACK_OF(TYPE) *sk);
103 \& TYPE *sk_TYPE_delete(STACK_OF(TYPE) *sk, int i);
104 \& TYPE *sk_TYPE_delete_ptr(STACK_OF(TYPE) *sk, TYPE *ptr);
105 \& int sk_TYPE_push(STACK_OF(TYPE) *sk, const TYPE *ptr);
106 \& int sk_TYPE_unshift(STACK_OF(TYPE) *sk, const TYPE *ptr);
107 \& TYPE *sk_TYPE_pop(STACK_OF(TYPE) *sk);
108 \& TYPE *sk_TYPE_shift(STACK_OF(TYPE) *sk);
109 \& void sk_TYPE_pop_free(STACK_OF(TYPE) *sk, sk_TYPE_freefunc freefunc);
110 \& int sk_TYPE_insert(STACK_OF(TYPE) *sk, TYPE *ptr, int idx);
111 \& TYPE *sk_TYPE_set(STACK_OF(TYPE) *sk, int idx, const TYPE *ptr);
112 \& int sk_TYPE_find(STACK_OF(TYPE) *sk, TYPE *ptr);
113 \& int sk_TYPE_find_ex(STACK_OF(TYPE) *sk, TYPE *ptr);
114 \& int sk_TYPE_find_all(STACK_OF(TYPE) *sk, TYPE *ptr, int *pnum);
115 \& void sk_TYPE_sort(const STACK_OF(TYPE) *sk);
116 \& int sk_TYPE_is_sorted(const STACK_OF(TYPE) *sk);
117 \& STACK_OF(TYPE) *sk_TYPE_dup(const STACK_OF(TYPE) *sk);
118 \& STACK_OF(TYPE) *sk_TYPE_deep_copy(const STACK_OF(TYPE) *sk,
119 \& sk_TYPE_copyfunc copyfunc,
120 \& sk_TYPE_freefunc freefunc);
121 \& sk_TYPE_compfunc (*sk_TYPE_set_cmp_func(STACK_OF(TYPE) *sk,
122 \& sk_TYPE_compfunc compare));
123 \& STACK_OF(TYPE) *sk_TYPE_new_reserve(sk_TYPE_compfunc compare, int n);
124 .Ve
125 .SH DESCRIPTION
126 .IX Header "DESCRIPTION"
127 Applications can create and use their own stacks by placing any of the macros
128 described below in a header file. These macros define typesafe inline
129 functions that wrap around the utility \fBOPENSSL_sk_\fR API.
130 In the description here, \fR\f(BITYPE\fR\fB\fR is used
131 as a placeholder for any of the OpenSSL datatypes, such as \fBX509\fR.
132 .PP
133 The \fBSTACK_OF()\fR macro returns the name for a stack of the specified \fR\f(BITYPE\fR\fB\fR.
134 This is an opaque pointer to a structure declaration.
135 This can be used in every header file that references the stack.
136 There are several \fBDEFINE...\fR macros that create static inline functions
137 for all of the functions described on this page.
138 This should normally be used in one source file, and the stack manipulation
139 is wrapped with application-specific functions.
140 .PP
141 \&\fBDEFINE_STACK_OF()\fR creates set of functions for a stack of \fR\f(BITYPE\fR\fB\fR elements.
142 The type is referenced by
143 \&\fBSTACK_OF\fR(\fB\fR\f(BITYPE\fR\fB\fR) and each function name begins with \fBsk_\fR\f(BITYPE\fR\fB_\fR.
144 \&\fBDEFINE_STACK_OF_CONST()\fR is identical to \fBDEFINE_STACK_OF()\fR except
145 each element is constant.
146 .PP
147 .Vb 4
148 \& /* DEFINE_STACK_OF(TYPE) */
149 \& TYPE *sk_TYPE_value(STACK_OF(TYPE) *sk, int idx);
150 \& /* DEFINE_STACK_OF_CONST(TYPE) */
151 \& const TYPE *sk_TYPE_value(STACK_OF(TYPE) *sk, int idx);
152 .Ve
153 .PP
154 \&\fBDEFINE_SPECIAL_STACK_OF()\fR and \fBDEFINE_SPECIAL_STACK_OF_CONST()\fR are similar
155 except \fBFUNCNAME\fR is used in the function names:
156 .PP
157 .Vb 4
158 \& /* DEFINE_SPECIAL_STACK_OF(TYPE, FUNCNAME) */
159 \& TYPE *sk_FUNCNAME_value(STACK_OF(TYPE) *sk, int idx);
160 \& /* DEFINE_SPECIAL_STACK_OF(TYPE, FUNCNAME) */
161 \& const TYPE *sk_FUNCNAME_value(STACK_OF(TYPE) *sk, int idx);
162 .Ve
163 .PP
164 \&\fBsk_\fR\f(BITYPE\fR\fB_num\fR() returns the number of elements in \fIsk\fR or \-1 if \fIsk\fR is
165 NULL.
166 .PP
167 \&\fBsk_\fR\f(BITYPE\fR\fB_value\fR() returns element \fIidx\fR in \fIsk\fR, where \fIidx\fR starts at
168 zero. If \fIidx\fR is out of range then NULL is returned.
169 .PP
170 \&\fBsk_\fR\f(BITYPE\fR\fB_new\fR() allocates a new empty stack using comparison function
171 \&\fIcompare\fR. If \fIcompare\fR is NULL then no comparison function is used. This
172 function is equivalent to \fBsk_\fR\f(BITYPE\fR\fB_new_reserve\fR(\fIcompare\fR, 0).
173 .PP
174 \&\fBsk_\fR\f(BITYPE\fR\fB_new_null\fR() allocates a new empty stack with no comparison
175 function. This function is equivalent to \fBsk_\fR\f(BITYPE\fR\fB_new_reserve\fR(NULL, 0).
176 .PP
177 \&\fBsk_\fR\f(BITYPE\fR\fB_reserve\fR() allocates additional memory in the \fIsk\fR structure
178 such that the next \fIn\fR calls to \fBsk_\fR\f(BITYPE\fR\fB_insert\fR(), \fBsk_\fR\f(BITYPE\fR\fB_push\fR()
179 or \fBsk_\fR\f(BITYPE\fR\fB_unshift\fR() will not fail or cause memory to be allocated
180 or reallocated. If \fIn\fR is zero, any excess space allocated in the
181 \&\fIsk\fR structure is freed. On error \fIsk\fR is unchanged.
182 .PP
183 \&\fBsk_\fR\f(BITYPE\fR\fB_new_reserve\fR() allocates a new stack. The new stack will have
184 additional memory allocated to hold \fIn\fR elements if \fIn\fR is positive.
185 The next \fIn\fR calls to \fBsk_\fR\f(BITYPE\fR\fB_insert\fR(), \fBsk_\fR\f(BITYPE\fR\fB_push\fR() or
186 \&\fBsk_\fR\f(BITYPE\fR\fB_unshift\fR() will not fail or cause memory to be allocated or
187 reallocated. If \fIn\fR is zero or less than zero, no memory is allocated.
188 \&\fBsk_\fR\f(BITYPE\fR\fB_new_reserve\fR() also sets the comparison function \fIcompare\fR
189 to the newly created stack. If \fIcompare\fR is NULL then no comparison
190 function is used.
191 .PP
192 \&\fBsk_\fR\f(BITYPE\fR\fB_set_cmp_func\fR() sets the comparison function of \fIsk\fR to
193 \&\fIcompare\fR. The previous comparison function is returned or NULL if there
194 was no previous comparison function.
195 .PP
196 \&\fBsk_\fR\f(BITYPE\fR\fB_free\fR() frees up the \fIsk\fR structure. It does \fInot\fR free up any
197 elements of \fIsk\fR. After this call \fIsk\fR is no longer valid.
198 .PP
199 \&\fBsk_\fR\f(BITYPE\fR\fB_zero\fR() sets the number of elements in \fIsk\fR to zero. It does not
200 free \fIsk\fR so after this call \fIsk\fR is still valid.
201 .PP
202 \&\fBsk_\fR\f(BITYPE\fR\fB_pop_free\fR() frees up all elements of \fIsk\fR and \fIsk\fR itself. The
203 free function \fBfreefunc()\fR is called on each element to free it.
204 .PP
205 \&\fBsk_\fR\f(BITYPE\fR\fB_delete\fR() deletes element \fIi\fR from \fIsk\fR. It returns the deleted
206 element or NULL if \fIi\fR is out of range.
207 .PP
208 \&\fBsk_\fR\f(BITYPE\fR\fB_delete_ptr\fR() deletes element matching \fIptr\fR from \fIsk\fR. It
209 returns the deleted element or NULL if no element matching \fIptr\fR was found.
210 .PP
211 \&\fBsk_\fR\f(BITYPE\fR\fB_insert\fR() inserts \fIptr\fR into \fIsk\fR at position \fIidx\fR. Any
212 existing elements at or after \fIidx\fR are moved downwards. If \fIidx\fR is out
213 of range the new element is appended to \fIsk\fR. \fBsk_\fR\f(BITYPE\fR\fB_insert\fR() either
214 returns the number of elements in \fIsk\fR after the new element is inserted or
215 zero if an error (such as memory allocation failure) occurred.
216 .PP
217 \&\fBsk_\fR\f(BITYPE\fR\fB_push\fR() appends \fIptr\fR to \fIsk\fR it is equivalent to:
218 .PP
219 .Vb 1
220 \& sk_TYPE_insert(sk, ptr, \-1);
221 .Ve
222 .PP
223 \&\fBsk_\fR\f(BITYPE\fR\fB_unshift\fR() inserts \fIptr\fR at the start of \fIsk\fR it is equivalent
224 to:
225 .PP
226 .Vb 1
227 \& sk_TYPE_insert(sk, ptr, 0);
228 .Ve
229 .PP
230 \&\fBsk_\fR\f(BITYPE\fR\fB_pop\fR() returns and removes the last element from \fIsk\fR.
231 .PP
232 \&\fBsk_\fR\f(BITYPE\fR\fB_shift\fR() returns and removes the first element from \fIsk\fR.
233 .PP
234 \&\fBsk_\fR\f(BITYPE\fR\fB_set\fR() sets element \fIidx\fR of \fIsk\fR to \fIptr\fR replacing the current
235 element. The new element value is returned or NULL if an error occurred:
236 this will only happen if \fIsk\fR is NULL or \fIidx\fR is out of range.
237 .PP
238 \&\fBsk_\fR\f(BITYPE\fR\fB_find\fR() searches \fIsk\fR for the element \fIptr\fR. In the
239 case where no comparison function has been specified, the function
240 performs a linear search for a pointer equal to \fIptr\fR. In the case
241 where a comparison function has been specified, the function performs
242 a search for a element that the comparison function indicates is a
243 match. If the stack is sorted, a binary search is used, otherwise, a
244 linear search is used. \fBsk_\fR\f(BITYPE\fR\fB_find\fR() returns the index of a
245 matching element or \fB\-1\fR if there is no match.
246 .PP
247 \&\fBsk_\fR\f(BITYPE\fR\fB_find_ex\fR() operates like \fBsk_\fR\f(BITYPE\fR\fB_find\fR() except when a
248 comparison function has been specified and no matching element is found.
249 Instead of returning \fB\-1\fR, \fBsk_\fR\f(BITYPE\fR\fB_find_ex\fR() returns the index of the
250 element either before or after the location where \fIptr\fR would be if it were
251 present in \fIsk\fR. The function also does not guarantee that the first matching
252 element in the sorted stack is returned.
253 .PP
254 \&\fBsk_\fR\f(BITYPE\fR\fB_find_all\fR() operates like \fBsk_\fR\f(BITYPE\fR\fB_find\fR() but it also
255 sets the \fI*pnum\fR to number of matching elements in the stack. In case
256 no comparison function has been specified the \fI*pnum\fR will be always set
257 to 1 if matching element was found, 0 otherwise.
258 .PP
259 \&\fBsk_\fR\f(BITYPE\fR\fB_sort\fR() sorts \fIsk\fR using the supplied comparison function.
260 .PP
261 \&\fBsk_\fR\f(BITYPE\fR\fB_is_sorted\fR() returns \fB1\fR if \fIsk\fR is sorted and \fB0\fR otherwise.
262 .PP
263 \&\fBsk_\fR\f(BITYPE\fR\fB_dup\fR() returns a shallow copy of \fIsk\fR
264 or an empty stack if the passed stack is NULL.
265 Note the pointers in the copy are identical to the original.
266 .PP
267 \&\fBsk_\fR\f(BITYPE\fR\fB_deep_copy\fR() returns a new stack where each element has been
268 copied or an empty stack if the passed stack is NULL.
269 Copying is performed by the supplied \fBcopyfunc()\fR and freeing by \fBfreefunc()\fR.
270 The function \fBfreefunc()\fR is only called if an error occurs.
271 .SH NOTES
272 .IX Header "NOTES"
273 Care should be taken when accessing stacks in multi-threaded environments.
274 Any operation which increases the size of a stack such as \fBsk_\fR\f(BITYPE\fR\fB_insert\fR()
275 or \fBsk_\fR\f(BITYPE\fR\fB_push\fR() can "grow" the size of an internal array and cause race
276 conditions if the same stack is accessed in a different thread. Operations such
277 as \fBsk_\fR\f(BITYPE\fR\fB_find\fR() and \fBsk_\fR\f(BITYPE\fR\fB_sort\fR() can also reorder the stack.
278 .PP
279 Any comparison function supplied should use a metric suitable
280 for use in a binary search operation. That is it should return zero, a
281 positive or negative value if \fIa\fR is equal to, greater than
282 or less than \fIb\fR respectively.
283 .PP
284 Care should be taken when checking the return values of the functions
285 \&\fBsk_\fR\f(BITYPE\fR\fB_find\fR() and \fBsk_\fR\f(BITYPE\fR\fB_find_ex\fR(). They return an index to the
286 matching element. In particular \fB0\fR indicates a matching first element.
287 A failed search is indicated by a \fB\-1\fR return value.
288 .PP
289 \&\fBSTACK_OF()\fR, \fBDEFINE_STACK_OF()\fR, \fBDEFINE_STACK_OF_CONST()\fR, and
290 \&\fBDEFINE_SPECIAL_STACK_OF()\fR are implemented as macros.
291 .PP
292 It is not an error to call \fBsk_\fR\f(BITYPE\fR\fB_num\fR(), \fBsk_\fR\f(BITYPE\fR\fB_value\fR(),
293 \&\fBsk_\fR\f(BITYPE\fR\fB_free\fR(), \fBsk_\fR\f(BITYPE\fR\fB_zero\fR(), \fBsk_\fR\f(BITYPE\fR\fB_pop_free\fR(),
294 \&\fBsk_\fR\f(BITYPE\fR\fB_delete\fR(), \fBsk_\fR\f(BITYPE\fR\fB_delete_ptr\fR(), \fBsk_\fR\f(BITYPE\fR\fB_pop\fR(),
295 \&\fBsk_\fR\f(BITYPE\fR\fB_shift\fR(), \fBsk_\fR\f(BITYPE\fR\fB_find\fR(), \fBsk_\fR\f(BITYPE\fR\fB_find_ex\fR(),
296 and \fBsk_\fR\f(BITYPE\fR\fB_find_all\fR() on a NULL stack, empty stack, or with
297 an invalid index. An error is not raised in these conditions.
298 .PP
299 The underlying utility \fBOPENSSL_sk_\fR API should not be used directly.
300 It defines these functions: \fBOPENSSL_sk_deep_copy()\fR,
301 \&\fBOPENSSL_sk_delete()\fR, \fBOPENSSL_sk_delete_ptr()\fR, \fBOPENSSL_sk_dup()\fR,
302 \&\fBOPENSSL_sk_find()\fR, \fBOPENSSL_sk_find_ex()\fR, \fBOPENSSL_sk_find_all()\fR,
303 \&\fBOPENSSL_sk_free()\fR, \fBOPENSSL_sk_insert()\fR, \fBOPENSSL_sk_is_sorted()\fR,
304 \&\fBOPENSSL_sk_new()\fR, \fBOPENSSL_sk_new_null()\fR, \fBOPENSSL_sk_new_reserve()\fR,
305 \&\fBOPENSSL_sk_num()\fR, \fBOPENSSL_sk_pop()\fR, \fBOPENSSL_sk_pop_free()\fR, \fBOPENSSL_sk_push()\fR,
306 \&\fBOPENSSL_sk_reserve()\fR, \fBOPENSSL_sk_set()\fR, \fBOPENSSL_sk_set_cmp_func()\fR,
307 \&\fBOPENSSL_sk_set_thunks()\fR, \fBOPENSSL_sk_shift()\fR, \fBOPENSSL_sk_sort()\fR,
308 \&\fBOPENSSL_sk_unshift()\fR, \fBOPENSSL_sk_value()\fR, \fBOPENSSL_sk_zero()\fR.
309 .PP
310 \&\fBOPENSSL_sk_set_thunks()\fR, while public by necessity, is actually an internal
311 function and should not be used.
312 .SH "RETURN VALUES"
313 .IX Header "RETURN VALUES"
314 \&\fBsk_\fR\f(BITYPE\fR\fB_num\fR() returns the number of elements in the stack or \fB\-1\fR if the
315 passed stack is NULL.
316 .PP
317 \&\fBsk_\fR\f(BITYPE\fR\fB_value\fR() returns a pointer to a stack element or NULL if the
318 index is out of range.
319 .PP
320 \&\fBsk_\fR\f(BITYPE\fR\fB_new\fR(), \fBsk_\fR\f(BITYPE\fR\fB_new_null\fR() and \fBsk_\fR\f(BITYPE\fR\fB_new_reserve\fR()
321 return an empty stack or NULL if an error occurs.
322 .PP
323 \&\fBsk_\fR\f(BITYPE\fR\fB_reserve\fR() returns \fB1\fR on successful allocation of the required
324 memory or \fB0\fR on error.
325 .PP
326 \&\fBsk_\fR\f(BITYPE\fR\fB_set_cmp_func\fR() returns the old comparison function or NULL if
327 there was no old comparison function.
328 .PP
329 \&\fBsk_\fR\f(BITYPE\fR\fB_free\fR(), \fBsk_\fR\f(BITYPE\fR\fB_zero\fR(), \fBsk_\fR\f(BITYPE\fR\fB_pop_free\fR() and
330 \&\fBsk_\fR\f(BITYPE\fR\fB_sort\fR() do not return values.
331 .PP
332 \&\fBsk_\fR\f(BITYPE\fR\fB_pop\fR(), \fBsk_\fR\f(BITYPE\fR\fB_shift\fR(), \fBsk_\fR\f(BITYPE\fR\fB_delete\fR() and
333 \&\fBsk_\fR\f(BITYPE\fR\fB_delete_ptr\fR() return a pointer to the deleted element or NULL
334 on error.
335 .PP
336 \&\fBsk_\fR\f(BITYPE\fR\fB_insert\fR(), \fBsk_\fR\f(BITYPE\fR\fB_push\fR() and \fBsk_\fR\f(BITYPE\fR\fB_unshift\fR() return
337 the total number of elements in the stack and 0 if an error occurred.
338 .PP
339 \&\fBsk_\fR\f(BITYPE\fR\fB_set\fR() returns a pointer to the replacement element or NULL on
340 error.
341 .PP
342 \&\fBsk_\fR\f(BITYPE\fR\fB_find\fR() and \fBsk_\fR\f(BITYPE\fR\fB_find_ex\fR() return an index to the found
343 element or \fB\-1\fR on error.
344 .PP
345 \&\fBsk_\fR\f(BITYPE\fR\fB_is_sorted\fR() returns \fB1\fR if the stack is sorted and \fB0\fR if it is
346 not.
347 .PP
348 \&\fBsk_\fR\f(BITYPE\fR\fB_dup\fR() and \fBsk_\fR\f(BITYPE\fR\fB_deep_copy\fR() return a pointer to the copy
349 of the stack or NULL on error.
350 .SH HISTORY
351 .IX Header "HISTORY"
352 Before OpenSSL 1.1.0, this was implemented via macros and not inline functions
353 and was not a public API.
354 .PP
355 \&\fBsk_\fR\f(BITYPE\fR\fB_reserve\fR() and \fBsk_\fR\f(BITYPE\fR\fB_new_reserve\fR() were added in OpenSSL
356 1.1.1.
357 .PP
358 From OpenSSL 3.2.0, the \fBsk_\fR\f(BITYPE\fR\fB_find\fR(), \fBsk_\fR\f(BITYPE\fR\fB_find_ex\fR()
359 and \fBsk_\fR\f(BITYPE\fR\fB_find_all\fR() calls are read-only and do not sort the
360 stack. To avoid any performance implications this change introduces,
361 \&\fBsk_\fR\f(BITYPE\fR\fB_sort\fR() should be called before these find operations.
362 .PP
363 Before OpenSSL 3.3.0 \fBsk_\fR\f(BITYPE\fR\fB_push\fR() returned \-1 if \fIsk\fR was NULL. It
364 was changed to return 0 in this condition as for other errors.
365 .PP
366 \&\fBOPENSSL_sk_set_thunks()\fR was added in OpenSSL 3.6.0.
367 .SH COPYRIGHT
368 .IX Header "COPYRIGHT"
369 Copyright 2000\-2025 The OpenSSL Project Authors. All Rights Reserved.
370 .PP
371 Licensed under the Apache License 2.0 (the "License"). You may not use
372 this file except in compliance with the License. You can obtain a copy
373 in the file LICENSE in the source distribution or at
374 <https://www.openssl.org/source/license.html>.