X-Git-Url: https://git.openssl.org/gitweb/?p=openssl.git;a=blobdiff_plain;f=doc%2Fman3%2FDEFINE_STACK_OF.pod;h=4dd3de843f80dbf481936a48a4ba3d1b8276140d;hp=43a3214d584a98a262391667b3c13d13453e4cb8;hb=6d4e6009d27712a405e1e3a4c33fb8a8566f134a;hpb=689c17883ac20d0991427b822eb98d2f0e6b78e7 diff --git a/doc/man3/DEFINE_STACK_OF.pod b/doc/man3/DEFINE_STACK_OF.pod index 43a3214d58..4dd3de843f 100644 --- a/doc/man3/DEFINE_STACK_OF.pod +++ b/doc/man3/DEFINE_STACK_OF.pod @@ -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 @@ -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 API. -In the description here, I is used -as a placeholder for any of the OpenSSL datatypes, such as I. +In the description here, B> is used +as a placeholder for any of the OpenSSL datatypes, such as B. -STACK_OF() returns the name for a stack of the specified B. -DEFINE_STACK_OF() creates set of functions for a stack of B. This -will mean that type B is stored in each stack, the type is referenced by -STACK_OF(TYPE) and each function name begins with I. For example: +STACK_OF() returns the name for a stack of the specified B>. +DEFINE_STACK_OF() creates set of functions for a stack of B>. This +will mean that type B> is stored in each stack, the type is referenced by +B(B>) and each function name begins with B_>. +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 but +DEFINE_SPECIAL_STACK_OF() defines a stack of B> but each function uses B 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 or -1 if B is -B. +B_num>() returns the number of elements in I or -1 if I is +NULL. -sk_TYPE_value() returns element B in B, where B starts at -zero. If B is out of range then B is returned. +B_value>() returns element I in I, where I starts at +zero. If I is out of range then NULL is returned. -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). +B_new>() allocates a new empty stack using comparison function +I. If I is NULL then no comparison function is used. This +function is equivalent to B_new_reserve>(I, 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_new_null>() allocates a new empty stack with no comparison +function. This function is equivalent to B_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() -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. +B_reserve>() allocates additional memory in the I structure +such that the next I calls to B_insert>(), B_push>() +or B_unshift>() will not fail or cause memory to be allocated +or reallocated. If I is zero, any excess space allocated in the +I structure is freed. On error I is unchanged. -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. +B_new_reserve>() allocates a new stack. The new stack will have +additional memory allocated to hold I elements if I is positive. +The next I calls to B_insert>(), B_push>() or +B_unshift>() will not fail or cause memory to be allocated or +reallocated. If I is zero or less than zero, no memory is allocated. +B_new_reserve>() also sets the comparison function I +to the newly created stack. If I is NULL 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. +B_set_cmp_func>() sets the comparison function of I to +I. The previous comparison function is returned or NULL if there +was no previous comparison function. -sk_TYPE_free() frees up the B structure. It does B free up any -elements of B. After this call B is no longer valid. +B_free>() frees up the I structure. It does I free up any +elements of I. After this call I is no longer valid. -sk_TYPE_zero() sets the number of elements in B to zero. It does not free -B so after this call B is still valid. +B_zero>() sets the number of elements in I to zero. It does not +free I so after this call I is still valid. -sk_TYPE_pop_free() frees up all elements of B and B itself. The +B_pop_free>() frees up all elements of I and I itself. The free function freefunc() is called on each element to free it. -sk_TYPE_delete() deletes element B from B. It returns the deleted -element or B if B is out of range. +B_delete>() deletes element I from I. It returns the deleted +element or NULL if I is out of range. -sk_TYPE_delete_ptr() deletes element matching B from B. It returns -the deleted element or B if no element matching B was found. +B_delete_ptr>() deletes element matching I from I. It +returns the deleted element or NULL if no element matching I was found. -sk_TYPE_insert() inserts B into B at position B. Any existing -elements at or after B are moved downwards. If B is out of range -the new element is appended to B. sk_TYPE_insert() either returns the -number of elements in B after the new element is inserted or zero if -an error (such as memory allocation failure) occurred. +B_insert>() inserts I into I at position I. Any +existing elements at or after I are moved downwards. If I is out +of range the new element is appended to I. B_insert>() either +returns the number of elements in I after the new element is inserted or +zero if an error (such as memory allocation failure) occurred. -sk_TYPE_push() appends B to B it is equivalent to: +B_push>() appends I to I it is equivalent to: sk_TYPE_insert(sk, ptr, -1); -sk_TYPE_unshift() inserts B at the start of B it is equivalent to: +B_unshift>() inserts I at the start of I it is equivalent +to: sk_TYPE_insert(sk, ptr, 0); -sk_TYPE_pop() returns and removes the last element from B. +B_pop>() returns and removes the last element from I. -sk_TYPE_shift() returns and removes the first element from B. +B_shift>() returns and removes the first element from I. -sk_TYPE_set() sets element B of B to B replacing the current -element. The new element value is returned or B if an error occurred: -this will only happen if B is B or B is out of range. +B_set>() sets element I of I to I replacing the current +element. The new element value is returned or NULL if an error occurred: +this will only happen if I is NULL or I is out of range. -sk_TYPE_find() searches B for the element B. In the case +B_find>() searches I for the element I. In the case where no comparison function has been specified, the function performs -a linear search for a pointer equal to B. The index of the first +a linear search for a pointer equal to I. 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 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 is sorted then +B_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 could change. +the order of elements in I 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 would be if it were -present in B. +B_find_ex>() operates like B_find>() except when a +comparison function has been specified and no matching element is found. +Instead of returning B<-1>, B_find_ex>() returns the index of the +element either before or after the location where I would be if it were +present in I. -sk_TYPE_sort() sorts B using the supplied comparison function. +B_sort>() sorts I using the supplied comparison function. -sk_TYPE_is_sorted() returns B<1> if B is sorted and B<0> otherwise. +B_is_sorted>() returns B<1> if I is sorted and B<0> otherwise. -sk_TYPE_dup() returns a copy of B. Note the pointers in the copy +B_dup>() returns a copy of I. 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_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_insert>() +or B_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_find>() and B_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 is equal to, greater than -or less than B respectively. +positive or negative value if I is equal to, greater than +or less than I 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_find>() and B_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,54 +219,56 @@ 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. +B_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 if the +B_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 if an error occurs. +B_new>(), B_new_null>() and B_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_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 if +B_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_free>(), B_zero>(), B_pop_free>() and +B_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 on error. +B_pop>(), B_shift>(), B_delete>() and +B_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_insert>(), B_push>() and B_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 on +B_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_find>() and B_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_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_dup>() and B_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_reserve>() and B_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.