doc/crypto/sk_X509_num.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 sk_X509_num, sk_X509_value, sk_X509_new, sk_X509_new_null, sk_X509_free,
   6 sk_X509_zero, sk_X509_delete, sk_X509_delete_ptr, sk_X509_push,
   7 sk_X509_unshift, sk_X509_pop, sk_X509_shift, sk_X509_pop_free, sk_X509_insert,
   8 sk_X509_set, sk_X509_find, sk_X509_find_ex, sk_X509_sort, sk_X509_is_sorted,
   9 sk_X509_dup, sk_X509_deep_copy, sk_X509_set_cmp_func - X509 stack
  10
  11 =head1 SYNOPSIS
  12
  13  #include <openssl/x509.h>
  14
  15  int sk_X509_num(const STACK_OF(X509) *sk);
  16  X509 *sk_X509_value(const STACK_OF(X509) *sk, int idx);
  17  STACK_OF(X509) *sk_X509_new(int (*cmpf)(const X509 * const *a,
  18                                          const X509 * const *b));
  19  STACK_OF(X509) *sk_X509_new_null(void);
  20  int (*sk_X509_set_cmp_func (STACK_OF(X509) *sk,
  21                              int (*cmpf) (const X509 * const *a,
  22                                           const X509 * const *b)))
  23                              (const X509 * const *, const X509 * const *);
  24  void sk_X509_free(const STACK_OF(X509) *sk);
  25  void sk_X509_zero(const STACK_OF(X509) *sk);
  26  void sk_X509_pop_free(STACK_OF(X509) *sk, void (*func) (X509 *a));
  27  X509 *sk_X509_delete(STACK_OF(X509) *sk, int i);
  28  X509 *sk_X509_delete_ptr(STACK_OF(X509) *sk, X509 *ptr);
  29  int sk_X509_insert(STACK_OF(X509) *sk, X509 *ptr, int idx);
  30  int sk_X509_push(STACK_OF(X509) *sk, X509 *ptr);
  31  int sk_X509_unshift(STACK_OF(X509) *sk, X509 *ptr);
  32  X509 *sk_X509_pop(STACK_OF(X509) *sk);
  33  X509 *sk_X509_shift(STACK_OF(X509) *sk);
  34  X509 *sk_X509_set(STACK_OF(X509) *sk, int idx, X509 *ptr);
  35  int sk_X509_find(STACK_OF(X509) *sk, X509 *ptr);
  36  int sk_X509_find_ex(STACK_OF(X509) *sk, X509 *ptr);
  37  void sk_X509_sort(const STACK_OF(X509) *sk);
  38  int sk_X509_is_sorted(const STACK_OF(X509) *sk);
  39  STACK_OF(X509) *sk_X509_dup(STACK_OF(X509) *sk);
  40  STACK_OF(X509) *sk_X509_deep_copy(STACK_OF(X509) *sk,
  41                                    X509 * (*copyfn) (const X509 *),
  42                                    void (*freefn) (X509 *));
  43
  44 =head1 DESCRIPTION
  45
  46 sk_X509_num() returns the number of elements in B<sk> or -1 if B<sk> is
  47 B<NULL>.
  48
  49 sk_X509_value() returns element B<idx> in B<sk>. Where B<idx> runs from 0
  50 to sk_X509_num(sk) - 1 inclusive. If B<idx> is out of range then B<NULL>
  51 is returned.
  52
  53 sk_X509_new() allocates a new empty stack using comparison function B<cmpf>.
  54 If B<cmpf> is B<0> then no comparison function is used.
  55
  56 sk_X509_new_null() allocates a new empty stack with no comparison function.
  57
  58 sk_X509_set_cmp_func() sets the comparison function of B<sk> to B<cmpf>.
  59 The previous comparison function is returned or B<0> if there was
  60 no previous comparison function.
  61
  62 sk_X509_free() frees up the B<sk> structure. It does B<not> free up any
  63 elements of B<sk>. After this call B<sk> is no longer valid.
  64
  65 sk_X509_zero() sets the number of elements in B<sk> to zero. It does not free
  66 B<sk> so after this call B<sk> is still valid.
  67
  68 sk_X509_pop_free() frees up all elements of B<sk> and B<sk> itself. The
  69 free function func() is called on each element to free it.
  70
  71 sk_X509_delete() deletes element B<i> from B<sk>. It returns the deleted
  72 element or B<NULL> if B<i> is out of range.
  73
  74 sk_X509_delete_ptr() deletes element matching B<ptr> from B<sk>. It returns
  75 the deleted element or B<NULL> if no element matching B<ptr> was found.
  76
  77 sk_X509_insert() inserts B<ptr> into B<sk> at position B<idx>. Any existing
  78 elements at or after B<idx> are moved downwards. If B<idx> is out of range
  79 the new element is appended to B<sk>. sk_X509_insert() either returns the
  80 number of elements in B<sk> after the new element is inserted or zero if
  81 an error occurred: which will happen if there is a memory allocation failure.
  82
  83 sk_X509_push() appends B<ptr> to B<sk> it is equivalent to:
  84
  85  sk_X509_insert(sk, ptr, -1);
  86
  87 sk_X509_unshift() inserts B<ptr> at the start of B<sk> it is equivalent to:
  88
  89  sk_X509_insert(sk, ptr, 0);
  90
  91 sk_X509_pop() returns and removes the last element from B<sk>.
  92
  93 sk_X509_shift() returns and removes the first element from B<sk>.
  94
  95 sk_X509_set() sets element B<idx> of B<sk> to B<ptr> replacing the current
  96 element. The new element value is returned or B<NULL> if an error occurred:
  97 this will only happen if B<sk> is B<NULL> or B<idx> is out of range.
  98
  99 sk_X509_find() and int sk_X509_find_ex() search B<sk> using the supplied
 100 comparison function for an element matching B<ptr>. sk_X509_find() returns
 101 the index of the first matching element or B<-1> if there is no match.
 102 sk_X509_find_ex() returns a matching element or the nearest element that
 103 does not match B<ptr>. Note: if a comparison function is set then  B<sk> is
 104 sorted before the search which may change its order. If no comparison
 105 function is set then a linear search is made for a pointer matching B<ptr>
 106 and the stack is not reordered.
 107
 108 sk_X509_sort() sorts B<sk> using the supplied comparison function.
 109
 110 sk_X509_is_sorted() returns B<1> if B<sk> is sorted and B<0> otherwise.
 111
 112 sk_X509_dup() returns a copy of B<sk>. Note the pointers in the copy
 113 are identical to the original.
 114
 115 sk_X509_deep_copy() returns a new stack where each element has been copied.
 116 Copying is performed by the supplied copyfn() and freeing by freefn(). The
 117 function freefn() is only called if an error occurs.
 118
 119 =head1 NOTES
 120
 121 This manual page documents the functions which operate on a stack of
 122 B<X509> pointers. A stack can contain pointers to any structure with B<X509>
 123 replaced by the appropriate structure name.
 124
 125 Care should be taken when accessing stacks in multi-threaded environments.
 126 Any operation which increases the size of a stack such as sk_X509_insert() or
 127 sk_push() can "grow" the size of an internal array and cause race conditions
 128 if the same stack is accessed in a different thread. Operations such as
 129 sk_find() and sk_sort() can also reorder the stack.
 130
 131 Any comparison function supplied should use a metric suitable
 132 for use in a binary search operation. That is it should return zero, a
 133 positive or negative value if B<a> is equal to, greater than
 134 or less than B<b> respectively.
 135
 136 Care should be taken when checking the return values of the functions
 137 sk_X509_find() and sk_X509_find_ex(). They return an index to the
 138 matching element. In particular B<0> indicates a matching first element.
 139 A failed search is indicated by a B<-1> return value.
 140
 141 =head1 APPLICATION DEFINED STACKS
 142
 143 Applications can create and use their own stacks by placing any of the macros
 144 described below in a header file.
 145
 146 DEFINE_STACK_OF(NAME) creates set of functions for a stack of B<NAME>. This
 147 will mean that type B<NAME> is stored in each stack, the type is referenced by
 148 STACK_OF(NAME) and each function name begins with sk_NAME_. For example:
 149
 150  NAME *sk_NAME_value(STACK_OF(NAME) *sk, int idx);
 151
 152 DEFINE_STACK_OF_CONST(NAME) is identical to DEFINE_STACK_OF(NAME) except
 153 each element is constant for example:
 154
 155  const NAME *sk_name_value(STACK_OF(NAME) *sk, int idx);
 156
 157 DEFINE_SPECIAL_STACK_OF(FNAME, STNAME) defines a stack of B<STNAME> but
 158 each function uses B<FNAME>. For example:
 159
 160  STNAME *sk_FNAME_value(STACK_OF(STNAME) *sk, int idx);
 161
 162 =head1 RETURN VALUES
 163
 164 sk_X509_num() returns the number of elements in the stack or B<-1> if the
 165 passed stack is B<NULL>.
 166
 167 sk_X509_value() returns a pointer to a stack element or B<NULL> if the
 168 index is out of range.
 169
 170 sk_X509_new() and sk_X509_new_null() return an empty stack or B<NULL> if
 171 an error occurs.
 172
 173 sk_X509_set_cmp_func() returns the old comparison function or B<NULL> if
 174 there was no old comparison function.
 175
 176 sk_X509_free(), sk_X509_zero(), sk_X509_pop_free() and sk_X509_sort() do
 177 not return values.
 178
 179 sk_X509_pop(), sk_X509_shift(), sk_X509_delete() and sk_X509_delete_ptr()
 180 return a pointer to the deleted element or B<NULL> on error.
 181
 182 sk_X509_insert(), sk_X509_push() and sk_X509_unshift() return the total
 183 number of elements in the stack and 0 if an error occurred.
 184
 185 sk_X509_set() returns a pointer to the replacement element or B<NULL> on
 186 error.
 187
 188 sk_X509_find() and sk_X509_find_ex() return an index to the found element
 189 or B<-1> on error.
 190
 191 sk_X509_is_sorted() returns B<1> if the stack is sorted and B<0> if it is
 192 not.
 193
 194 sk_X509_dup() and sk_X509_deep_copy() return a pointer to the copy of the
 195 stack.
 196
 197 =head1 HISTORY
 198
 199 Use of inline functions and application defined stacks first appeared in
 200 OpenSSL 1.1.0. Previous versions of OpenSSL implemented stacks as macros.
 201
 202 =cut
 203
 204 =head1 COPYRIGHT
 205
 206 Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
 207
 208 Licensed under the OpenSSL license (the "License").  You may not use
 209 this file except in compliance with the License.  You can obtain a copy
 210 in the file LICENSE in the source distribution or at
 211 L<https://www.openssl.org/source/license.html>.
 212
 213 =cut