doc/man3/DEFINE_STACK_OF.pod

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