diff options
Diffstat (limited to 'doc/crypto/sk_X509_num.pod')
| -rw-r--r-- | doc/crypto/sk_X509_num.pod | 213 |
1 files changed, 0 insertions, 213 deletions
diff --git a/doc/crypto/sk_X509_num.pod b/doc/crypto/sk_X509_num.pod deleted file mode 100644 index 1f16e81954..0000000000 --- a/doc/crypto/sk_X509_num.pod +++ /dev/null @@ -1,213 +0,0 @@ -=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 <openssl/x509.h> - - 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<sk> or -1 if B<sk> is -B<NULL>. - -sk_X509_value() returns element B<idx> in B<sk>. Where B<idx> runs from 0 -to sk_X509_num(sk) - 1 inclusive. If B<idx> is out of range then B<NULL> -is returned. - -sk_X509_new() allocates a new empty stack using comparison function B<cmpf>. -If B<cmpf> 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<sk> to B<cmpf>. -The previous comparison function is returned or B<0> if there was -no previous comparison function. - -sk_X509_free() frees up the B<sk> structure. It does B<not> free up any -elements of B<sk>. After this call B<sk> is no longer valid. - -sk_X509_zero() sets the number of elements in B<sk> to zero. It does not free -B<sk> so after this call B<sk> is still valid. - -sk_X509_pop_free() frees up all elements of B<sk> and B<sk> itself. The -free function func() is called on each element to free it. - -sk_X509_delete() deletes element B<i> from B<sk>. It returns the deleted -element or B<NULL> if B<i> is out of range. - -sk_X509_delete_ptr() deletes element matching B<ptr> from B<sk>. It returns -the deleted element or B<NULL> if no element matching B<ptr> was found. - -sk_X509_insert() inserts B<ptr> into B<sk> at position B<idx>. Any existing -elements at or after B<idx> are moved downwards. If B<idx> is out of range -the new element is appended to B<sk>. sk_X509_insert() either returns the -number of elements in B<sk> after the new element is inserted or zero if -an error occurred: which will happen if there is a memory allocation failure. - -sk_X509_push() appends B<ptr> to B<sk> it is equivalent to: - - sk_X509_insert(sk, ptr, -1); - -sk_X509_unshift() inserts B<ptr> at the start of B<sk> it is equivalent to: - - sk_X509_insert(sk, ptr, 0); - -sk_X509_pop() returns and removes the last element from B<sk>. - -sk_X509_shift() returns and removes the first element from B<sk>. - -sk_X509_set() sets element B<idx> of B<sk> to B<ptr> replacing the current -element. The new element value is returned or B<NULL> if an error occurred: -this will only happen if B<sk> is B<NULL> or B<idx> is out of range. - -sk_X509_find() and int sk_X509_find_ex() search B<sk> using the supplied -comparison function for an element matching B<ptr>. 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<ptr>. Note: if a comparison function is set then B<sk> 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<ptr> -and the stack is not reordered. - -sk_X509_sort() sorts B<sk> using the supplied comparison function. - -sk_X509_is_sorted() returns B<1> if B<sk> is sorted and B<0> otherwise. - -sk_X509_dup() returns a copy of B<sk>. 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<X509> pointers. A stack can contain pointers to any structure with B<X509> -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<a> is equal to, greater than -or less than B<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<NAME>. This -will mean that type B<NAME> 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<STNAME> but -each function uses B<FNAME>. 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<NULL>. - -sk_X509_value() returns a pointer to a stack element or B<NULL> if the -index is out of range. - -sk_X509_new() and sk_X509_new_null() return an empty stack or B<NULL> if -an error occurs. - -sk_X509_set_cmp_func() returns the old comparison function or B<NULL> 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<NULL> 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<NULL> 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. - -=cut - -=head1 COPYRIGHT - -Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. - -Licensed under the OpenSSL license (the "License"). You may not use -this file except in compliance with the License. You can obtain a copy -in the file LICENSE in the source distribution or at -L<https://www.openssl.org/source/license.html>. - -=cut |