Latest update.
This commit is contained in:
+102
-97
@@ -14,7 +14,7 @@ sk_TYPE_dup, sk_TYPE_deep_copy, sk_TYPE_set_cmp_func, sk_TYPE_new_reserve
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
=for comment generic
|
||||
=for openssl generic
|
||||
|
||||
#include <openssl/safestack.h>
|
||||
|
||||
@@ -61,13 +61,14 @@ sk_TYPE_dup, sk_TYPE_deep_copy, sk_TYPE_set_cmp_func, sk_TYPE_new_reserve
|
||||
Applications can create and use their own stacks by placing any of the macros
|
||||
described below in a header file. These macros define typesafe inline
|
||||
functions that wrap around the utility B<OPENSSL_sk_> API.
|
||||
In the description here, I<TYPE> is used
|
||||
as a placeholder for any of the OpenSSL datatypes, such as I<X509>.
|
||||
In the description here, B<I<TYPE>> is used
|
||||
as a placeholder for any of the OpenSSL datatypes, such as B<X509>.
|
||||
|
||||
STACK_OF() returns the name for a stack of the specified B<TYPE>.
|
||||
DEFINE_STACK_OF() creates set of functions for a stack of B<TYPE>. This
|
||||
will mean that type B<TYPE> is stored in each stack, the type is referenced by
|
||||
STACK_OF(TYPE) and each function name begins with I<sk_TYPE_>. For example:
|
||||
STACK_OF() returns the name for a stack of the specified B<I<TYPE>>.
|
||||
DEFINE_STACK_OF() creates set of functions for a stack of B<I<TYPE>>. This
|
||||
will mean that type B<I<TYPE>> is stored in each stack, the type is referenced by
|
||||
B<STACK_OF>(B<I<TYPE>>) and each function name begins with B<sk_I<TYPE>_>.
|
||||
For example:
|
||||
|
||||
TYPE *sk_TYPE_value(STACK_OF(TYPE) *sk, int idx);
|
||||
|
||||
@@ -76,7 +77,7 @@ each element is constant. For example:
|
||||
|
||||
const TYPE *sk_TYPE_value(STACK_OF(TYPE) *sk, int idx);
|
||||
|
||||
DEFINE_SPECIAL_STACK_OF() defines a stack of B<TYPE> but
|
||||
DEFINE_SPECIAL_STACK_OF() defines a stack of B<I<TYPE>> but
|
||||
each function uses B<FUNCNAME> in the function name. For example:
|
||||
|
||||
TYPE *sk_FUNCNAME_value(STACK_OF(TYPE) *sk, int idx);
|
||||
@@ -86,117 +87,119 @@ constant:
|
||||
|
||||
const TYPE *sk_FUNCNAME_value(STACK_OF(TYPE) *sk, int idx);
|
||||
|
||||
sk_TYPE_num() returns the number of elements in B<sk> or -1 if B<sk> is
|
||||
B<NULL>.
|
||||
B<sk_I<TYPE>_num>() returns the number of elements in I<sk> or -1 if I<sk> is
|
||||
NULL.
|
||||
|
||||
sk_TYPE_value() returns element B<idx> in B<sk>, where B<idx> starts at
|
||||
zero. If B<idx> is out of range then B<NULL> is returned.
|
||||
B<sk_I<TYPE>_value>() returns element I<idx> in I<sk>, where I<idx> starts at
|
||||
zero. If I<idx> is out of range then NULL is returned.
|
||||
|
||||
sk_TYPE_new() allocates a new empty stack using comparison function B<compare>.
|
||||
If B<compare> is B<NULL> then no comparison function is used. This function is
|
||||
equivalent to sk_TYPE_new_reserve(compare, 0).
|
||||
B<sk_I<TYPE>_new>() allocates a new empty stack using comparison function
|
||||
I<compare>. If I<compare> is NULL then no comparison function is used. This
|
||||
function is equivalent to B<sk_I<TYPE>_new_reserve>(I<compare>, 0).
|
||||
|
||||
sk_TYPE_new_null() allocates a new empty stack with no comparison function. This
|
||||
function is equivalent to sk_TYPE_new_reserve(NULL, 0).
|
||||
B<sk_I<TYPE>_new_null>() allocates a new empty stack with no comparison
|
||||
function. This function is equivalent to B<sk_I<TYPE>_new_reserve>(NULL, 0).
|
||||
|
||||
sk_TYPE_reserve() allocates additional memory in the B<sk> structure
|
||||
such that the next B<n> calls to sk_TYPE_insert(), sk_TYPE_push()
|
||||
or sk_TYPE_unshift() will not fail or cause memory to be allocated
|
||||
or reallocated. If B<n> is zero, any excess space allocated in the
|
||||
B<sk> structure is freed. On error B<sk> is unchanged.
|
||||
B<sk_I<TYPE>_reserve>() allocates additional memory in the I<sk> structure
|
||||
such that the next I<n> calls to B<sk_I<TYPE>_insert>(), B<sk_I<TYPE>_push>()
|
||||
or B<sk_I<TYPE>_unshift>() will not fail or cause memory to be allocated
|
||||
or reallocated. If I<n> is zero, any excess space allocated in the
|
||||
I<sk> structure is freed. On error I<sk> is unchanged.
|
||||
|
||||
sk_TYPE_new_reserve() allocates a new stack. The new stack will have additional
|
||||
memory allocated to hold B<n> elements if B<n> is positive. The next B<n> calls
|
||||
to sk_TYPE_insert(), sk_TYPE_push() or sk_TYPE_unshift() will not fail or cause
|
||||
memory to be allocated or reallocated. If B<n> is zero or less than zero, no
|
||||
memory is allocated. sk_TYPE_new_reserve() also sets the comparison function
|
||||
B<compare> to the newly created stack. If B<compare> is B<NULL> then no
|
||||
comparison function is used.
|
||||
B<sk_I<TYPE>_new_reserve>() allocates a new stack. The new stack will have
|
||||
additional memory allocated to hold I<n> elements if I<n> is positive.
|
||||
The next I<n> calls to B<sk_I<TYPE>_insert>(), B<sk_I<TYPE>_push>() or
|
||||
B<sk_I<TYPE>_unshift>() will not fail or cause memory to be allocated or
|
||||
reallocated. If I<n> is zero or less than zero, no memory is allocated.
|
||||
B<sk_I<TYPE>_new_reserve>() also sets the comparison function I<compare>
|
||||
to the newly created stack. If I<compare> is NULL then no comparison
|
||||
function is used.
|
||||
|
||||
sk_TYPE_set_cmp_func() sets the comparison function of B<sk> to B<compare>.
|
||||
The previous comparison function is returned or B<NULL> if there was
|
||||
no previous comparison function.
|
||||
B<sk_I<TYPE>_set_cmp_func>() sets the comparison function of I<sk> to
|
||||
I<compare>. The previous comparison function is returned or NULL if there
|
||||
was no previous comparison function.
|
||||
|
||||
sk_TYPE_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.
|
||||
B<sk_I<TYPE>_free>() frees up the I<sk> structure. It does I<not> free up any
|
||||
elements of I<sk>. After this call I<sk> is no longer valid.
|
||||
|
||||
sk_TYPE_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.
|
||||
B<sk_I<TYPE>_zero>() sets the number of elements in I<sk> to zero. It does not
|
||||
free I<sk> so after this call I<sk> is still valid.
|
||||
|
||||
sk_TYPE_pop_free() frees up all elements of B<sk> and B<sk> itself. The
|
||||
B<sk_I<TYPE>_pop_free>() frees up all elements of I<sk> and I<sk> itself. The
|
||||
free function freefunc() is called on each element to free it.
|
||||
|
||||
sk_TYPE_delete() deletes element B<i> from B<sk>. It returns the deleted
|
||||
element or B<NULL> if B<i> is out of range.
|
||||
B<sk_I<TYPE>_delete>() deletes element I<i> from I<sk>. It returns the deleted
|
||||
element or NULL if I<i> is out of range.
|
||||
|
||||
sk_TYPE_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.
|
||||
B<sk_I<TYPE>_delete_ptr>() deletes element matching I<ptr> from I<sk>. It
|
||||
returns the deleted element or NULL if no element matching I<ptr> was found.
|
||||
|
||||
sk_TYPE_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_TYPE_insert() either returns the
|
||||
number of elements in B<sk> after the new element is inserted or zero if
|
||||
an error (such as memory allocation failure) occurred.
|
||||
B<sk_I<TYPE>_insert>() inserts I<ptr> into I<sk> at position I<idx>. Any
|
||||
existing elements at or after I<idx> are moved downwards. If I<idx> is out
|
||||
of range the new element is appended to I<sk>. B<sk_I<TYPE>_insert>() either
|
||||
returns the number of elements in I<sk> after the new element is inserted or
|
||||
zero if an error (such as memory allocation failure) occurred.
|
||||
|
||||
sk_TYPE_push() appends B<ptr> to B<sk> it is equivalent to:
|
||||
B<sk_I<TYPE>_push>() appends I<ptr> to I<sk> it is equivalent to:
|
||||
|
||||
sk_TYPE_insert(sk, ptr, -1);
|
||||
|
||||
sk_TYPE_unshift() inserts B<ptr> at the start of B<sk> it is equivalent to:
|
||||
B<sk_I<TYPE>_unshift>() inserts I<ptr> at the start of I<sk> it is equivalent
|
||||
to:
|
||||
|
||||
sk_TYPE_insert(sk, ptr, 0);
|
||||
|
||||
sk_TYPE_pop() returns and removes the last element from B<sk>.
|
||||
B<sk_I<TYPE>_pop>() returns and removes the last element from I<sk>.
|
||||
|
||||
sk_TYPE_shift() returns and removes the first element from B<sk>.
|
||||
B<sk_I<TYPE>_shift>() returns and removes the first element from I<sk>.
|
||||
|
||||
sk_TYPE_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.
|
||||
B<sk_I<TYPE>_set>() sets element I<idx> of I<sk> to I<ptr> replacing the current
|
||||
element. The new element value is returned or NULL if an error occurred:
|
||||
this will only happen if I<sk> is NULL or I<idx> is out of range.
|
||||
|
||||
sk_TYPE_find() searches B<sk> for the element B<ptr>. In the case
|
||||
B<sk_I<TYPE>_find>() searches I<sk> for the element I<ptr>. In the case
|
||||
where no comparison function has been specified, the function performs
|
||||
a linear search for a pointer equal to B<ptr>. The index of the first
|
||||
a linear search for a pointer equal to I<ptr>. The index of the first
|
||||
matching element is returned or B<-1> if there is no match. In the case
|
||||
where a comparison function has been specified, B<sk> is sorted then
|
||||
sk_TYPE_find() returns the index of a matching element or B<-1> if there
|
||||
where a comparison function has been specified, I<sk> is sorted then
|
||||
B<sk_I<TYPE>_find>() returns the index of a matching element or B<-1> if there
|
||||
is no match. Note that, in this case, the matching element returned is
|
||||
not guaranteed to be the first; the comparison function will usually
|
||||
compare the values pointed to rather than the pointers themselves and
|
||||
the order of elements in B<sk> could change.
|
||||
the order of elements in I<sk> could change.
|
||||
|
||||
sk_TYPE_find_ex() operates like sk_TYPE_find() except when a comparison
|
||||
function has been specified and no matching element is found. Instead
|
||||
of returning B<-1>, sk_TYPE_find_ex() returns the index of the element
|
||||
either before or after the location where B<ptr> would be if it were
|
||||
present in B<sk>.
|
||||
B<sk_I<TYPE>_find_ex>() operates like B<sk_I<TYPE>_find>() except when a
|
||||
comparison function has been specified and no matching element is found.
|
||||
Instead of returning B<-1>, B<sk_I<TYPE>_find_ex>() returns the index of the
|
||||
element either before or after the location where I<ptr> would be if it were
|
||||
present in I<sk>.
|
||||
|
||||
sk_TYPE_sort() sorts B<sk> using the supplied comparison function.
|
||||
B<sk_I<TYPE>_sort>() sorts I<sk> using the supplied comparison function.
|
||||
|
||||
sk_TYPE_is_sorted() returns B<1> if B<sk> is sorted and B<0> otherwise.
|
||||
B<sk_I<TYPE>_is_sorted>() returns B<1> if I<sk> is sorted and B<0> otherwise.
|
||||
|
||||
sk_TYPE_dup() returns a copy of B<sk>. Note the pointers in the copy
|
||||
B<sk_I<TYPE>_dup>() returns a copy of I<sk>. Note the pointers in the copy
|
||||
are identical to the original.
|
||||
|
||||
sk_TYPE_deep_copy() returns a new stack where each element has been copied.
|
||||
Copying is performed by the supplied copyfunc() and freeing by freefunc(). The
|
||||
function freefunc() is only called if an error occurs.
|
||||
B<sk_I<TYPE>_deep_copy>() returns a new stack where each element has been
|
||||
copied. Copying is performed by the supplied copyfunc() and freeing by
|
||||
freefunc(). The function freefunc() is only called if an error occurs.
|
||||
|
||||
=head1 NOTES
|
||||
|
||||
Care should be taken when accessing stacks in multi-threaded environments.
|
||||
Any operation which increases the size of a stack such as sk_TYPE_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 operation which increases the size of a stack such as B<sk_I<TYPE>_insert>()
|
||||
or B<sk_I<TYPE>_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 B<sk_I<TYPE>_find>() and B<sk_I<TYPE>_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.
|
||||
positive or negative value if I<a> is equal to, greater than
|
||||
or less than I<b> respectively.
|
||||
|
||||
Care should be taken when checking the return values of the functions
|
||||
sk_TYPE_find() and sk_TYPE_find_ex(). They return an index to the
|
||||
B<sk_I<TYPE>_find>() and B<sk_I<TYPE>_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.
|
||||
|
||||
@@ -216,48 +219,50 @@ OPENSSL_sk_zero().
|
||||
|
||||
=head1 RETURN VALUES
|
||||
|
||||
sk_TYPE_num() returns the number of elements in the stack or B<-1> if the
|
||||
passed stack is B<NULL>.
|
||||
B<sk_I<TYPE>_num>() returns the number of elements in the stack or B<-1> if the
|
||||
passed stack is NULL.
|
||||
|
||||
sk_TYPE_value() returns a pointer to a stack element or B<NULL> if the
|
||||
B<sk_I<TYPE>_value>() returns a pointer to a stack element or NULL if the
|
||||
index is out of range.
|
||||
|
||||
sk_TYPE_new(), sk_TYPE_new_null() and sk_TYPE_new_reserve() return an empty
|
||||
stack or B<NULL> if an error occurs.
|
||||
B<sk_I<TYPE>_new>(), B<sk_I<TYPE>_new_null>() and B<sk_I<TYPE>_new_reserve>()
|
||||
return an empty stack or NULL if an error occurs.
|
||||
|
||||
sk_TYPE_reserve() returns B<1> on successful allocation of the required memory
|
||||
or B<0> on error.
|
||||
B<sk_I<TYPE>_reserve>() returns B<1> on successful allocation of the required
|
||||
memory or B<0> on error.
|
||||
|
||||
sk_TYPE_set_cmp_func() returns the old comparison function or B<NULL> if
|
||||
B<sk_I<TYPE>_set_cmp_func>() returns the old comparison function or NULL if
|
||||
there was no old comparison function.
|
||||
|
||||
sk_TYPE_free(), sk_TYPE_zero(), sk_TYPE_pop_free() and sk_TYPE_sort() do
|
||||
not return values.
|
||||
B<sk_I<TYPE>_free>(), B<sk_I<TYPE>_zero>(), B<sk_I<TYPE>_pop_free>() and
|
||||
B<sk_I<TYPE>_sort>() do not return values.
|
||||
|
||||
sk_TYPE_pop(), sk_TYPE_shift(), sk_TYPE_delete() and sk_TYPE_delete_ptr()
|
||||
return a pointer to the deleted element or B<NULL> on error.
|
||||
B<sk_I<TYPE>_pop>(), B<sk_I<TYPE>_shift>(), B<sk_I<TYPE>_delete>() and
|
||||
B<sk_I<TYPE>_delete_ptr>() return a pointer to the deleted element or NULL
|
||||
on error.
|
||||
|
||||
sk_TYPE_insert(), sk_TYPE_push() and sk_TYPE_unshift() return the total
|
||||
number of elements in the stack and 0 if an error occurred.
|
||||
B<sk_I<TYPE>_insert>(), B<sk_I<TYPE>_push>() and B<sk_I<TYPE>_unshift>() return
|
||||
the total number of elements in the stack and 0 if an error occurred.
|
||||
|
||||
sk_TYPE_set() returns a pointer to the replacement element or B<NULL> on
|
||||
B<sk_I<TYPE>_set>() returns a pointer to the replacement element or NULL on
|
||||
error.
|
||||
|
||||
sk_TYPE_find() and sk_TYPE_find_ex() return an index to the found element
|
||||
or B<-1> on error.
|
||||
B<sk_I<TYPE>_find>() and B<sk_I<TYPE>_find_ex>() return an index to the found
|
||||
element or B<-1> on error.
|
||||
|
||||
sk_TYPE_is_sorted() returns B<1> if the stack is sorted and B<0> if it is
|
||||
B<sk_I<TYPE>_is_sorted>() returns B<1> if the stack is sorted and B<0> if it is
|
||||
not.
|
||||
|
||||
sk_TYPE_dup() and sk_TYPE_deep_copy() return a pointer to the copy of the
|
||||
stack.
|
||||
B<sk_I<TYPE>_dup>() and B<sk_I<TYPE>_deep_copy>() return a pointer to the copy
|
||||
of the stack.
|
||||
|
||||
=head1 HISTORY
|
||||
|
||||
Before OpenSSL 1.1.0, this was implemented via macros and not inline functions
|
||||
and was not a public API.
|
||||
|
||||
sk_TYPE_reserve() and sk_TYPE_new_reserve() were added in OpenSSL 1.1.1.
|
||||
B<sk_I<TYPE>_reserve>() and B<sk_I<TYPE>_new_reserve>() were added in OpenSSL
|
||||
1.1.1.
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
|
||||
Reference in New Issue
Block a user