From 48cc4ad020213c83c34b225820522fe64163b522 Mon Sep 17 00:00:00 2001 From: "Dr. Stephen Henson" Date: Tue, 12 Jan 2016 16:21:23 +0000 Subject: [PATCH] Stack documentation. Reviewed-by: Matt Caswell --- doc/crypto/sk_X509_num.pod | 200 +++++++++++++++++++++++++++++++++++++ 1 file changed, 200 insertions(+) create mode 100644 doc/crypto/sk_X509_num.pod diff --git a/doc/crypto/sk_X509_num.pod b/doc/crypto/sk_X509_num.pod new file mode 100644 index 0000000000..79002d4a44 --- /dev/null +++ b/doc/crypto/sk_X509_num.pod @@ -0,0 +1,200 @@ +=pod + +=head1 NAME + +sk_X509_num, sk_X509_value, sk_X509_new, sk_X509_new_null, sk_X509_free, +sk_X509_zero, sk_X509_delete, sk_X509_delete_ptr, sk_X509_push, +sk_X509_unshift, sk_X509_pop, sk_X509_shift, sk_X509_pop_free, sk_X509_insert, +sk_X509_set, sk_X509_find, sk_X509_find_ex, sk_X509_sort, sk_X509_is_sorted, +sk_X509_dup, sk_X509_deep_copy, sk_X509_set_cmp_func - X509 stack + +=head1 SYNOPSIS + + #include + + int sk_X509_num(const STACK_OF(X509) *sk); + X509 *sk_X509_value(const STACK_OF(X509) *sk, int idx); + STACK_OF(X509) *sk_X509_new(int (*cmpf)(const X509 * const *a, + const X509 * const *b)); + STACK_OF(X509) *sk_X509_new_null(void); + int (*sk_X509_set_cmp_func (STACK_OF(X509) *sk, + int (*cmpf) (const X509 * const *a, + const X509 * const *b))) + (const X509 * const *, const X509 * const *); + void sk_X509_free(const STACK_OF(X509) *sk); + void sk_X509_zero(const STACK_OF(X509) *sk); + void sk_X509_pop_free(STACK_OF(X509) *sk, void (*func) (X509 *a)); + X509 *sk_X509_delete(STACK_OF(X509) *sk, int i); + X509 *sk_X509_delete_ptr(STACK_OF(X509) *sk, X509 *ptr); + int sk_X509_insert(STACK_OF(X509) *sk, X509 *ptr, int idx); + int sk_X509_push(STACK_OF(X509) *sk, X509 *ptr); + int sk_X509_unshift(STACK_OF(X509) *sk, X509 *ptr); + X509 *sk_X509_pop(STACK_OF(X509) *sk); + X509 *sk_X509_shift(STACK_OF(X509) *sk); + X509 *sk_X509_set(STACK_OF(X509) *sk, int idx, X509 *ptr); + int sk_X509_find(STACK_OF(X509) *sk, X509 *ptr); + int sk_X509_find_ex(STACK_OF(X509) *sk, X509 *ptr); + void sk_X509_sort(const STACK_OF(X509) *sk); + int sk_X509_is_sorted(const STACK_OF(X509) *sk); + STACK_OF(X509) *sk_X509_dup(STACK_OF(X509) *sk); + STACK_OF(X509) *sk_X509_deep_copy(STACK_OF(X509) *sk, + X509 * (*copyfn) (const X509 *), + void (*freefn) (X509 *)); + +=head1 DESCRIPTION + +sk_X509_num() returns the number of elements in B or -1 if B is +B. + +sk_X509_value() returns element B in B. Where B runs from 0 +to sk_X509_num(sk) - 1 inclusive. If B is out of range then B +is returned. + +sk_X509_new() allocates a new empty stack using comparison function B. +If B is B<0> then no comparison function is used. + +sk_X509_new_null() allocates a new empty stack with no comparison function. + +sk_X509_set_cmp_func() sets the comparison function of B to B. +The previous comparison function is returned or B<0> if there was +no previous comparison function. + +sk_X509_free() frees up the B structure. It does B free up any +elements of B. After this call B is no longer valid. + +sk_X509_zero() sets the number of elements in B to zero. It does not free +B so after this call B is still valid. + +sk_X509_pop_free() frees up all elements of B and B itself. The +free function func() is called on each element to free it. + +sk_X509_delete() deletes element B from B. It returns the deleted +element or B if B is out of range. + +sk_X509_delete_ptr() deletes element matching B from B. It returns +the deleted element or B if no element matching B was found. + +sk_X509_insert() inserts B into B at position B. Any existing +elements at or after B are moved downwards. If B is out of range +the new element is appended to B. sk_X509_insert() either returns the +number of elements in B after the new element is inserted or zero if +an error occured: which will happen if there is a memory allocation failure. + +sk_X509_push() appends B to B it is equivalent to: + + sk_X509_insert(sk, ptr, -1); + +sk_X509_unshift() inserts B at the start of B it is equivalent to: + + sk_X509_insert(sk, ptr, 0); + +sk_X509_pop() returns and removes the last element from B. + +sk_X509_shift() returns and removes the first element from B. + +sk_X509_set() sets element B of B to B replacing the current +element. The new element value is returned or B if an error occured: +this will only happen if B is B or B is out of range. + +sk_X509_find() and int sk_X509_find_ex() search B using the supplied +comparison function for an element matching B. sk_X509_find() returns +the index of the first matching element or B<-1> if there is no match. +sk_X509_find_ex() returns a matching element or the nearest element that +does not match B. Note: if a comparison function is set then B is +sorted before the search which may change its order. If no comparison +function is set then a linear search is made for a pointer matching B +and the stack is not reordered. + +sk_X509_sort() sorts B using the supplied comparison function. + +sk_X509_is_sorted() returns B<1> if B is sorted and B<0> otherwise. + +sk_X509_dup() returns a copy of B. Note the pointers in the copy +are identical to the original. + +sk_X509_deep_copy() returns a new stack where each element has been copied. +Copying is performed by the supplied copyfn() and freeing by freefn(). The +function freefn() is only called if an error occurs. + +=head1 NOTES + +This manual page documents the functions which operate on a stack of +B pointers. A stack can contain pointers to any structure with B +replaced by the appropriate structure name. + +Care should be taken when accessing stacks in multi-threaded environments. +Any operation which increases the size of a stack such as sk_X509_insert() or +sk_push() can "grow" the size of an internal array and cause race conditions +if the same stack is accessed in a different thread. Operations such as +sk_find() and sk_sort() can also reorder the stack. + +Any comparison function supplied should use a metric suitable +for use in a binary search operation. That is it should return zero, a +positive or negative value if B is equal to, greater than +or less than B respectively. + +Care should be taken when checking the return values of the functions +sk_X509_find() and sk_X509_find_ex(). They return an index to the +matching element. In particular B<0> indicates a matching first element. +A failed search is indicated by a B<-1> return value. + +=head1 APPLICATION DEFINED STACKS + +Applications can create and use their own stacks by placing any of the macros +described below in a header file. + +DEFINE_STACK_OF(NAME) creates set of functions for a stack of B. This +will mean that type B is stored in each stack, the type is referenced by +STACK_OF(NAME) and each function name begins with sk_NAME_. For example: + + NAME *sk_NAME_value(STACK_OF(NAME) *sk, int idx); + +DEFINE_STACK_OF_CONST(NAME) is identical to DEFINE_STACK_OF(NAME) except +each element is constant for example: + + const NAME *sk_name_value(STACK_OF(NAME) *sk, int idx); + +DEFINE_SPECIAL_STACK_OF(FNAME, STNAME) defines a stack of B but +each function uses B. For example: + + STNAME *sk_FNAME_value(STACK_OF(STNAME) *sk, int idx); + +=head1 RETURN VALUES + +sk_X509_num() returns the number of elements in the stack or B<-1> if the +passed stack is B. + +sk_X509_value() returns a pointer to a stack element or B if the +index is out of range. + +sk_X509_new() and sk_X509_new_null() return an empty stack or B if +an error occurs. + +sk_X509_set_cmp_func() returns the old comparison function or B if +there was no old comparison function. + +sk_X509_free(), sk_X509_zero(), sk_X509_pop_free() and sk_X509_sort() do +not return values. + +sk_X509_pop(), sk_X509_shift(), sk_X509_delete() and sk_X509_delete_ptr() +return a pointer to the deleted element or B on error. + +sk_X509_insert(), sk_X509_push() and sk_X509_unshift() return the total +number of elements in the stack and 0 if an error occurred. + +sk_X509_set() returns a pointer to the replacement element or B on +error. + +sk_X509_find() and sk_X509_find_ex() return an index to the found element +or B<-1> on error. + +sk_X509_is_sorted() returns B<1> if the stack is sorted and B<0> if it is +not. + +sk_X509_dup() and sk_X509_deep_copy() return a pointer to the copy of the +stack. + +=head1 HISTORY + +Use of inline functions and application defined stacks first appeared in +OpenSSL 1.1.0. Previous versions of OpenSSL implemented stacks as macros. -- 2.34.1