doc/crypto/sk_X509_num.pod - third_party/openssl - Git at Google

 =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
	=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