DEFINE_STACK_OF, DEFINE_STACK_OF_CONST, DEFINE_SPECIAL_STACK_OF,
DEFINE_SPECIAL_STACK_OF_CONST,
-OPENSSL_sk_deep_copy, OPENSSL_sk_delete, OPENSSL_sk_delete_ptr,
-OPENSSL_sk_dup, OPENSSL_sk_find, OPENSSL_sk_find_ex, OPENSSL_sk_free,
-OPENSSL_sk_insert, OPENSSL_sk_is_sorted, OPENSSL_sk_new, OPENSSL_sk_new_null,
-OPENSSL_sk_num, OPENSSL_sk_pop, OPENSSL_sk_pop_free, OPENSSL_sk_push,
-OPENSSL_sk_set, OPENSSL_sk_set_cmp_func, OPENSSL_sk_shift, OPENSSL_sk_sort,
-OPENSSL_sk_unshift, OPENSSL_sk_value, OPENSSL_sk_zero,
-sk_TYPE_num, sk_TYPE_value, sk_TYPE_new, sk_TYPE_new_null, sk_TYPE_free,
-sk_TYPE_zero, sk_TYPE_delete, sk_TYPE_delete_ptr, sk_TYPE_push,
-sk_TYPE_unshift, sk_TYPE_pop, sk_TYPE_shift, sk_TYPE_pop_free,
-sk_TYPE_insert, sk_TYPE_set, sk_TYPE_find, sk_TYPE_find_ex, sk_TYPE_sort,
-sk_TYPE_is_sorted, sk_TYPE_dup, sk_TYPE_deep_copy, sk_TYPE_set_cmp_func -
-stack container
-
-=for comment generic
+sk_TYPE_num, sk_TYPE_value, sk_TYPE_new, sk_TYPE_new_null,
+sk_TYPE_reserve, sk_TYPE_free, sk_TYPE_zero, sk_TYPE_delete,
+sk_TYPE_delete_ptr, sk_TYPE_push, sk_TYPE_unshift, sk_TYPE_pop,
+sk_TYPE_shift, sk_TYPE_pop_free, sk_TYPE_insert, sk_TYPE_set,
+sk_TYPE_find, sk_TYPE_find_ex, sk_TYPE_sort, sk_TYPE_is_sorted,
+sk_TYPE_dup, sk_TYPE_deep_copy, sk_TYPE_set_cmp_func, sk_TYPE_new_reserve
+- stack container
=head1 SYNOPSIS
+=for comment generic
+
#include <openssl/safestack.h>
STACK_OF(TYPE)
TYPE *sk_TYPE_value(const STACK_OF(TYPE) *sk, int idx);
STACK_OF(TYPE) *sk_TYPE_new(sk_TYPE_compfunc compare);
STACK_OF(TYPE) *sk_TYPE_new_null(void);
+ int sk_TYPE_reserve(STACK_OF(TYPE) *sk, int n);
void sk_TYPE_free(const STACK_OF(TYPE) *sk);
void sk_TYPE_zero(const STACK_OF(TYPE) *sk);
TYPE *sk_TYPE_delete(STACK_OF(TYPE) *sk, int i);
STACK_OF(TYPE) *sk_TYPE_deep_copy(const STACK_OF(TYPE) *sk,
sk_TYPE_copyfunc copyfunc,
sk_TYPE_freefunc freefunc);
- sk_TYPE_compfunc (*sk_TYPE_set_cmp_func(STACK_OF(TYPE) *sk, sk_TYPE_compfunc compare);
+ sk_TYPE_compfunc (*sk_TYPE_set_cmp_func(STACK_OF(TYPE) *sk,
+ sk_TYPE_compfunc compare));
+ STACK_OF(TYPE) *sk_TYPE_new_reserve(sk_TYPE_compfunc compare, int n);
=head1 DESCRIPTION
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.
-sk_TYPE_new() allocates a new empty stack using comparison function B<compar>.
-If B<compar> is B<NULL> then no comparison function is used.
+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).
+
+sk_TYPE_new_null() allocates a new empty stack with no comparison function. This
+function is equivalent to sk_TYPE_new_reserve(NULL, 0).
-sk_TYPE_new_null() allocates a new empty stack with no comparison function.
+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.
-sk_TYPE_set_cmp_func() sets the comparison function of B<sk> to B<compar>.
+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.
+
+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.
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_TYPE_find() and sk_TYPE_find_ex() search B<sk> using the supplied
-comparison function for an element matching B<ptr>. sk_TYPE_find() returns
-the index of the first matching element or B<-1> if there is no match.
-sk_TYPE_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_TYPE_find() searches B<sk> for the element B<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
+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
+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.
+
+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>.
sk_TYPE_sort() sorts B<sk> using the supplied comparison function.
STACK_OF(), DEFINE_STACK_OF(), DEFINE_STACK_OF_CONST(), and
DEFINE_SPECIAL_STACK_OF() are implemented as macros.
+The underlying utility B<OPENSSL_sk_> API should not be used directly.
+It defines these functions: OPENSSL_sk_deep_copy(),
+OPENSSL_sk_delete(), OPENSSL_sk_delete_ptr(), OPENSSL_sk_dup(),
+OPENSSL_sk_find(), OPENSSL_sk_find_ex(), OPENSSL_sk_free(),
+OPENSSL_sk_insert(), OPENSSL_sk_is_sorted(), OPENSSL_sk_new(),
+OPENSSL_sk_new_null(), OPENSSL_sk_num(), OPENSSL_sk_pop(),
+OPENSSL_sk_pop_free(), OPENSSL_sk_push(), OPENSSL_sk_reserve(),
+OPENSSL_sk_set(), OPENSSL_sk_set_cmp_func(), OPENSSL_sk_shift(),
+OPENSSL_sk_sort(), OPENSSL_sk_unshift(), OPENSSL_sk_value(),
+OPENSSL_sk_zero().
+
=head1 RETURN VALUES
sk_TYPE_num() returns the number of elements in the stack or B<-1> if the
sk_TYPE_value() returns a pointer to a stack element or B<NULL> if the
index is out of range.
-sk_TYPE_new() and sk_TYPE_new_null() return an empty stack or B<NULL> if
-an error occurs.
+sk_TYPE_new(), sk_TYPE_new_null() and sk_TYPE_new_reserve() return an empty
+stack or B<NULL> if an error occurs.
+
+sk_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
there was no old comparison function.
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.
+
=head1 COPYRIGHT
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2000-2017 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
projects / openssl.git / blobdiff