| 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>. |