X-Git-Url: https://git.openssl.org/?p=openssl.git;a=blobdiff_plain;f=doc%2Fman3%2FDEFINE_STACK_OF.pod;h=f658c760db3d2e4d8e8779f3d6ae0af896d8217e;hp=a9fc769f2bf33a70fecfb7c28337f31a37f3730d;hb=3dcbb6c4a395d56dfa561145d89017ff958bb18e;hpb=1b3e2bbf64b96f636277ca29b31ba152c1831e74 diff --git a/doc/man3/DEFINE_STACK_OF.pod b/doc/man3/DEFINE_STACK_OF.pod index a9fc769f2b..f658c760db 100644 --- a/doc/man3/DEFINE_STACK_OF.pod +++ b/doc/man3/DEFINE_STACK_OF.pod @@ -4,19 +4,13 @@ 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_reserve, 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_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 - stack container +sk_TYPE_dup, sk_TYPE_deep_copy, sk_TYPE_set_cmp_func, sk_TYPE_new_reserve +- stack container =head1 SYNOPSIS @@ -38,7 +32,7 @@ sk_TYPE_dup, sk_TYPE_deep_copy, sk_TYPE_set_cmp_func - stack container 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, size_t n); + 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); @@ -60,6 +54,7 @@ sk_TYPE_dup, sk_TYPE_deep_copy, sk_TYPE_set_cmp_func - stack container sk_TYPE_freefunc freefunc); 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 @@ -97,10 +92,12 @@ B. sk_TYPE_value() returns element B in B, where B starts at zero. If B is out of range then B is returned. -sk_TYPE_new() allocates a new empty stack using comparison function B. -If B is B then no comparison function is used. +sk_TYPE_new() allocates a new empty stack using comparison function B. +If B is B 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. +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_reserve() allocates additional memory in the B structure such that the next B calls to sk_TYPE_insert(), sk_TYPE_push() @@ -108,7 +105,15 @@ or sk_TYPE_unshift() will not fail or cause memory to be allocated or reallocated. If B is zero, any excess space allocated in the B structure is freed. On error B is unchanged. -sk_TYPE_set_cmp_func() sets the comparison function of B to B. +sk_TYPE_new_reserve() allocates a new stack. The new stack will have additional +memory allocated to hold B elements if B is positive. The next B 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 is zero or less than zero, no +memory is allocated. sk_TYPE_new_reserve() also sets the comparison function +B to the newly created stack. If B is B then no +comparison function is used. + +sk_TYPE_set_cmp_func() sets the comparison function of B to B. The previous comparison function is returned or B if there was no previous comparison function. @@ -198,6 +203,17 @@ A failed search is indicated by a B<-1> return value. STACK_OF(), DEFINE_STACK_OF(), DEFINE_STACK_OF_CONST(), and DEFINE_SPECIAL_STACK_OF() are implemented as macros. +The underlying utility B 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 @@ -206,8 +222,8 @@ passed stack is B. sk_TYPE_value() returns a pointer to a stack element or B if the index is out of range. -sk_TYPE_new() and sk_TYPE_new_null() return an empty stack or B if -an error occurs. +sk_TYPE_new(), sk_TYPE_new_null() and sk_TYPE_new_reserve() return an empty +stack or B if an error occurs. sk_TYPE_reserve() returns B<1> on successful allocation of the required memory or B<0> on error. @@ -241,11 +257,13 @@ stack. 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-2017 The OpenSSL Project Authors. All Rights Reserved. -Licensed under the OpenSSL license (the "License"). You may not use +Licensed under the Apache License 2.0 (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.