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