root
/
openssl
mirror of https://github.com/openssl/openssl.git
1
0
Fork 0
Code Issues Actions 7 Packages Projects Releases Wiki Activity
openssl/doc/man3/DEFINE_STACK_OF.pod

Ignoring revisions in .git-blame-ignore-revs. Click here to bypass and see the normal blame view.

312 lines
14 KiB
Plaintext
Raw Normal View History

Rename lh_xxx,sk_xxx tp OPENSSL_{LH,SK}_xxx Rename sk_xxx to OPENSSL_sk_xxx and _STACK to OPENSSL_STACK Rename lh_xxx API to OPENSSL_LH_xxx and LHASH_NODE to OPENSSL_LH_NODE Make lhash stuff opaque. Use typedefs for function pointers; makes the code simpler. Remove CHECKED_xxx macros. Add documentation; remove old X509-oriented doc. Add API-compat names for entire old API Reviewed-by: Dr. Stephen Henson <steve@openssl.org>
2016-05-20 22:46:29 +08:00
=pod
=head1 NAME
DEFINE_STACK_OF, DEFINE_STACK_OF_CONST, DEFINE_SPECIAL_STACK_OF,
Replace all #define's in pod pages. Function-like macros are replaced with prototypes and a note that they are implemented as macros. Constants are just referenced in-line in the text. Tweak BIO_TYPE_... documentation. Also fix RT4592. Reviewed-by: Matt Caswell <matt@openssl.org>
2016-07-09 00:55:45 +08:00
DEFINE_SPECIAL_STACK_OF_CONST,
Add a reserve call to the stack data structure. This allows the caller to guarantee that there is sufficient space for a number of insertions without reallocation. The expansion ratio when reallocating the array is reduced to 1.5 rather than 2. Change bounds testing to use a single size rather than both INT_MAX and SIZE_MAX. This simplifies some of the tests. Switch the stack pointers to data from char * to void * Reviewed-by: Andy Polyakov <appro@openssl.org> (Merged from https://github.com/openssl/openssl/pull/4386)
2017-08-17 08:10:07 +08:00
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,
Improve the implementation of X509_STORE_CTX_get1_issuer() It is possible for the stack of X509_OBJECTs held in an X509_STORE_CTX to have a custom compare function associated with it. Normally (by default) this uses X509_NAME_cmp(). The X509_STORE_CTX_get1_issuer() function assumed that it would always be X509_NAME_cmp(). By implementing OPENSSL_sk_find_all() function we can avoid explicitly using X509_NAME_cmp() in X509_STORE_CTX_get1_issuer(). Reviewed-by: Matt Caswell <matt@openssl.org> (Merged from https://github.com/openssl/openssl/pull/14728)
2021-03-29 18:41:18 +08:00
sk_TYPE_find, sk_TYPE_find_ex, sk_TYPE_find_all, sk_TYPE_sort,
sk_TYPE_is_sorted, sk_TYPE_dup, sk_TYPE_deep_copy, sk_TYPE_set_cmp_func,
OPENSSL_sk functions are effectively already documented Reviewed-by: Matt Caswell <matt@openssl.org> (Merged from https://github.com/openssl/openssl/pull/14728)
2021-03-29 20:18:10 +08:00
sk_TYPE_new_reserve,
OPENSSL_sk_deep_copy, OPENSSL_sk_delete, OPENSSL_sk_delete_ptr,
OPENSSL_sk_dup, OPENSSL_sk_find, OPENSSL_sk_find_ex, OPENSSL_sk_find_all,
OPENSSL_sk_free, OPENSSL_sk_insert, OPENSSL_sk_is_sorted, OPENSSL_sk_new,
OPENSSL_sk_new_null, OPENSSL_sk_new_reserve, 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
Add sk_TYPE_new_reserve() function This is a combination of sk_new and sk_reserve, to make it more convenient to allocate a new stack with reserved memory and comaprison function (if any). Reviewed-by: Paul Dale <paul.dale@oracle.com> Reviewed-by: Andy Polyakov <appro@openssl.org> Reviewed-by: Richard Levitte <levitte@openssl.org> (Merged from https://github.com/openssl/openssl/pull/4559)
2017-10-20 01:42:39 +08:00
- stack container
Rename lh_xxx,sk_xxx tp OPENSSL_{LH,SK}_xxx Rename sk_xxx to OPENSSL_sk_xxx and _STACK to OPENSSL_STACK Rename lh_xxx API to OPENSSL_LH_xxx and LHASH_NODE to OPENSSL_LH_NODE Make lhash stuff opaque. Use typedefs for function pointers; makes the code simpler. Remove CHECKED_xxx macros. Add documentation; remove old X509-oriented doc. Add API-compat names for entire old API Reviewed-by: Dr. Stephen Henson <steve@openssl.org>
2016-05-20 22:46:29 +08:00
=head1 SYNOPSIS
POD: stop abusing comment OpenSSL uses some POD directives masquerading as 'comment' ('=for comment' etc). This is abusive and confusing. Instead, we use our own keyword. =for openssl whatever =begin openssl whatever =end openssl (we have never used the multiline form, but might start one day) Reviewed-by: Tomas Mraz <tmraz@fedoraproject.org> (Merged from https://github.com/openssl/openssl/pull/10048)
2019-09-29 23:10:59 +08:00
=for openssl generic
Fix referenses in section 3 manuals Reviewed-by: Rich Salz <rsalz@openssl.org> (Merged from https://github.com/openssl/openssl/pull/1900)
2016-11-11 16:33:09 +08:00
Rename lh_xxx,sk_xxx tp OPENSSL_{LH,SK}_xxx Rename sk_xxx to OPENSSL_sk_xxx and _STACK to OPENSSL_STACK Rename lh_xxx API to OPENSSL_LH_xxx and LHASH_NODE to OPENSSL_LH_NODE Make lhash stuff opaque. Use typedefs for function pointers; makes the code simpler. Remove CHECKED_xxx macros. Add documentation; remove old X509-oriented doc. Add API-compat names for entire old API Reviewed-by: Dr. Stephen Henson <steve@openssl.org>
2016-05-20 22:46:29 +08:00
#include <openssl/safestack.h>
Replace all #define's in pod pages. Function-like macros are replaced with prototypes and a note that they are implemented as macros. Constants are just referenced in-line in the text. Tweak BIO_TYPE_... documentation. Also fix RT4592. Reviewed-by: Matt Caswell <matt@openssl.org>
2016-07-09 00:55:45 +08:00
STACK_OF(TYPE)
DEFINE_STACK_OF(TYPE)
DEFINE_STACK_OF_CONST(TYPE)
DEFINE_SPECIAL_STACK_OF(FUNCTYPE, TYPE)
DEFINE_SPECIAL_STACK_OF_CONST(FUNCTYPE, TYPE)
Rename lh_xxx,sk_xxx tp OPENSSL_{LH,SK}_xxx Rename sk_xxx to OPENSSL_sk_xxx and _STACK to OPENSSL_STACK Rename lh_xxx API to OPENSSL_LH_xxx and LHASH_NODE to OPENSSL_LH_NODE Make lhash stuff opaque. Use typedefs for function pointers; makes the code simpler. Remove CHECKED_xxx macros. Add documentation; remove old X509-oriented doc. Add API-compat names for entire old API Reviewed-by: Dr. Stephen Henson <steve@openssl.org>
2016-05-20 22:46:29 +08:00
typedef int (*sk_TYPE_compfunc)(const TYPE *const *a, const TYPE *const *b);
typedef TYPE * (*sk_TYPE_copyfunc)(const TYPE *a);
typedef void (*sk_TYPE_freefunc)(TYPE *a);
int sk_TYPE_num(const STACK_OF(TYPE) *sk);
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);
Fix mismatch of function prototype and document Reviewed-by: Paul Dale <paul.dale@oracle.com> Reviewed-by: Andy Polyakov <appro@openssl.org> Reviewed-by: Richard Levitte <levitte@openssl.org> (Merged from https://github.com/openssl/openssl/pull/4559)
2017-10-20 13:11:37 +08:00
int sk_TYPE_reserve(STACK_OF(TYPE) *sk, int n);
DEFINE_STACK_OF.pod: Fix prototypes of sk_TYPE_free/zero() They take non-const STACK_OF(TYPE)* argument. Reviewed-by: Neil Horman <nhorman@openssl.org> Reviewed-by: Matt Caswell <matt@openssl.org> Reviewed-by: Paul Dale <ppzgs1@gmail.com> (Merged from https://github.com/openssl/openssl/pull/24023)
2024-04-02 22:43:27 +08:00
void sk_TYPE_free(STACK_OF(TYPE) *sk);
void sk_TYPE_zero(STACK_OF(TYPE) *sk);
Rename lh_xxx,sk_xxx tp OPENSSL_{LH,SK}_xxx Rename sk_xxx to OPENSSL_sk_xxx and _STACK to OPENSSL_STACK Rename lh_xxx API to OPENSSL_LH_xxx and LHASH_NODE to OPENSSL_LH_NODE Make lhash stuff opaque. Use typedefs for function pointers; makes the code simpler. Remove CHECKED_xxx macros. Add documentation; remove old X509-oriented doc. Add API-compat names for entire old API Reviewed-by: Dr. Stephen Henson <steve@openssl.org>
2016-05-20 22:46:29 +08:00
TYPE *sk_TYPE_delete(STACK_OF(TYPE) *sk, int i);
TYPE *sk_TYPE_delete_ptr(STACK_OF(TYPE) *sk, TYPE *ptr);
Add some const casts Reviewed-by: Matt Caswell <matt@openssl.org> (Merged from https://github.com/openssl/openssl/pull/1397)
2016-08-05 04:50:19 +08:00
int sk_TYPE_push(STACK_OF(TYPE) *sk, const TYPE *ptr);
int sk_TYPE_unshift(STACK_OF(TYPE) *sk, const TYPE *ptr);
Rename lh_xxx,sk_xxx tp OPENSSL_{LH,SK}_xxx Rename sk_xxx to OPENSSL_sk_xxx and _STACK to OPENSSL_STACK Rename lh_xxx API to OPENSSL_LH_xxx and LHASH_NODE to OPENSSL_LH_NODE Make lhash stuff opaque. Use typedefs for function pointers; makes the code simpler. Remove CHECKED_xxx macros. Add documentation; remove old X509-oriented doc. Add API-compat names for entire old API Reviewed-by: Dr. Stephen Henson <steve@openssl.org>
2016-05-20 22:46:29 +08:00
TYPE *sk_TYPE_pop(STACK_OF(TYPE) *sk);
TYPE *sk_TYPE_shift(STACK_OF(TYPE) *sk);
void sk_TYPE_pop_free(STACK_OF(TYPE) *sk, sk_TYPE_freefunc freefunc);
int sk_TYPE_insert(STACK_OF(TYPE) *sk, TYPE *ptr, int idx);
Add some const casts Reviewed-by: Matt Caswell <matt@openssl.org> (Merged from https://github.com/openssl/openssl/pull/1397)
2016-08-05 04:50:19 +08:00
TYPE *sk_TYPE_set(STACK_OF(TYPE) *sk, int idx, const TYPE *ptr);
Rename lh_xxx,sk_xxx tp OPENSSL_{LH,SK}_xxx Rename sk_xxx to OPENSSL_sk_xxx and _STACK to OPENSSL_STACK Rename lh_xxx API to OPENSSL_LH_xxx and LHASH_NODE to OPENSSL_LH_NODE Make lhash stuff opaque. Use typedefs for function pointers; makes the code simpler. Remove CHECKED_xxx macros. Add documentation; remove old X509-oriented doc. Add API-compat names for entire old API Reviewed-by: Dr. Stephen Henson <steve@openssl.org>
2016-05-20 22:46:29 +08:00
int sk_TYPE_find(STACK_OF(TYPE) *sk, TYPE *ptr);
int sk_TYPE_find_ex(STACK_OF(TYPE) *sk, TYPE *ptr);
Improve the implementation of X509_STORE_CTX_get1_issuer() It is possible for the stack of X509_OBJECTs held in an X509_STORE_CTX to have a custom compare function associated with it. Normally (by default) this uses X509_NAME_cmp(). The X509_STORE_CTX_get1_issuer() function assumed that it would always be X509_NAME_cmp(). By implementing OPENSSL_sk_find_all() function we can avoid explicitly using X509_NAME_cmp() in X509_STORE_CTX_get1_issuer(). Reviewed-by: Matt Caswell <matt@openssl.org> (Merged from https://github.com/openssl/openssl/pull/14728)
2021-03-29 18:41:18 +08:00
int sk_TYPE_find_all(STACK_OF(TYPE) *sk, TYPE *ptr, int *pnum);
Rename lh_xxx,sk_xxx tp OPENSSL_{LH,SK}_xxx Rename sk_xxx to OPENSSL_sk_xxx and _STACK to OPENSSL_STACK Rename lh_xxx API to OPENSSL_LH_xxx and LHASH_NODE to OPENSSL_LH_NODE Make lhash stuff opaque. Use typedefs for function pointers; makes the code simpler. Remove CHECKED_xxx macros. Add documentation; remove old X509-oriented doc. Add API-compat names for entire old API Reviewed-by: Dr. Stephen Henson <steve@openssl.org>
2016-05-20 22:46:29 +08:00
void sk_TYPE_sort(const STACK_OF(TYPE) *sk);
int sk_TYPE_is_sorted(const STACK_OF(TYPE) *sk);
Constify a bit more OPENSSL_sk_ API Reviewed-by: Richard Levitte <levitte@openssl.org> Reviewed-by: Rich Salz <rsalz@openssl.org> (Merged from https://github.com/openssl/openssl/pull/1244)
2016-06-18 21:05:24 +08:00
STACK_OF(TYPE) *sk_TYPE_dup(const STACK_OF(TYPE) *sk);
STACK_OF(TYPE) *sk_TYPE_deep_copy(const STACK_OF(TYPE) *sk,
Rename lh_xxx,sk_xxx tp OPENSSL_{LH,SK}_xxx Rename sk_xxx to OPENSSL_sk_xxx and _STACK to OPENSSL_STACK Rename lh_xxx API to OPENSSL_LH_xxx and LHASH_NODE to OPENSSL_LH_NODE Make lhash stuff opaque. Use typedefs for function pointers; makes the code simpler. Remove CHECKED_xxx macros. Add documentation; remove old X509-oriented doc. Add API-compat names for entire old API Reviewed-by: Dr. Stephen Henson <steve@openssl.org>
2016-05-20 22:46:29 +08:00
sk_TYPE_copyfunc copyfunc,
sk_TYPE_freefunc freefunc);
doc/man3: reformat the function prototypes in the synopses I tried hard to keep the lines at 80 characters or less, but in a few cases I had to punt and just indented the subsequent lines by 4 spaces. A few well-placed typedefs for callback functions would really help, but these would be part of the API, so that's probably for later. I also took the liberty of inserting empty lines in overlong blocks to provide some visual space. Reviewed-by: Rich Salz <rsalz@openssl.org> Reviewed-by: Matt Caswell <matt@openssl.org> (Merged from https://github.com/openssl/openssl/pull/1956)
2017-01-21 02:58:49 +08:00
sk_TYPE_compfunc (*sk_TYPE_set_cmp_func(STACK_OF(TYPE) *sk,
sk_TYPE_compfunc compare));
Add sk_TYPE_new_reserve() function This is a combination of sk_new and sk_reserve, to make it more convenient to allocate a new stack with reserved memory and comaprison function (if any). Reviewed-by: Paul Dale <paul.dale@oracle.com> Reviewed-by: Andy Polyakov <appro@openssl.org> Reviewed-by: Richard Levitte <levitte@openssl.org> (Merged from https://github.com/openssl/openssl/pull/4559)
2017-10-20 01:42:39 +08:00
STACK_OF(TYPE) *sk_TYPE_new_reserve(sk_TYPE_compfunc compare, int n);
Rename lh_xxx,sk_xxx tp OPENSSL_{LH,SK}_xxx Rename sk_xxx to OPENSSL_sk_xxx and _STACK to OPENSSL_STACK Rename lh_xxx API to OPENSSL_LH_xxx and LHASH_NODE to OPENSSL_LH_NODE Make lhash stuff opaque. Use typedefs for function pointers; makes the code simpler. Remove CHECKED_xxx macros. Add documentation; remove old X509-oriented doc. Add API-compat names for entire old API Reviewed-by: Dr. Stephen Henson <steve@openssl.org>
2016-05-20 22:46:29 +08:00
=head1 DESCRIPTION
Applications can create and use their own stacks by placing any of the macros
More doc cleanup Add missing entries to NAME section Add SYNOPSIS lines, remove old NAME entries Update find-doc-nits; better regexp's for parsing SYNOPSIS sections. Rename a couple of files to have an API name. Remove RSA_private_decrypt; it was duplicate content Update for recent doc additions Reviewed-by: Matt Caswell <matt@openssl.org>
2016-06-21 19:03:34 +08:00
described below in a header file. These macros define typesafe inline
functions that wrap around the utility B<OPENSSL_sk_> API.
Make manuals with TYPE conform with man-pages(7) Details from man-pages(7) that are used: Formatting conventions for manual pages describing functions ... Variable names should, like argument names, be specified in italics. ... Formatting conventions (general) ... Special macros, which are usually in uppercase, are in bold. Exception: don't boldface NULL. ... Furthermore, for TYPE used as a placeholder for types and correponding part of function names, we extrapolate that it's both a type and a variable, and should therefore be bold (typical for types and function names) and italic (typical for variables). POD processors don'e know this, so we have to help them along. Therefore: SPARSE_ARRAY_OF(TYPE) => B<SPARSE_ARRAY_OF>(B<I<TYPE>>) ossl_sa_TYPE_num() => B<ossl_sa_I<TYPE>_num>() TYPE => B<I<TYPE>> There are some other less typical uses where one simply has to give formatting some extra though. Reviewed-by: Matt Caswell <matt@openssl.org> (Merged from https://github.com/openssl/openssl/pull/10041)
2019-09-28 13:33:38 +08:00
In the description here, B<I<TYPE>> is used
as a placeholder for any of the OpenSSL datatypes, such as B<X509>.
Rename lh_xxx,sk_xxx tp OPENSSL_{LH,SK}_xxx Rename sk_xxx to OPENSSL_sk_xxx and _STACK to OPENSSL_STACK Rename lh_xxx API to OPENSSL_LH_xxx and LHASH_NODE to OPENSSL_LH_NODE Make lhash stuff opaque. Use typedefs for function pointers; makes the code simpler. Remove CHECKED_xxx macros. Add documentation; remove old X509-oriented doc. Add API-compat names for entire old API Reviewed-by: Dr. Stephen Henson <steve@openssl.org>
2016-05-20 22:46:29 +08:00
In OpenSSL builds, declare STACK for datatypes ... ... and only *define* them in the source files that need them. Use DEFINE_OR_DECLARE which is set appropriately for internal builds and not non-deprecated builds. Deprecate stack-of-block Better documentation Move some ASN1 struct typedefs to types.h Update ParseC to handle this. Most of all, ParseC needed to be more consistent. The handlers are "recursive", in so far that they are called again and again until they terminate, which depends entirely on what the "massager" returns. There's a comment at the beginning of ParseC that explains how that works. {Richard Levtte} Reviewed-by: Dmitry Belyavskiy <beldmit@gmail.com> Reviewed-by: Tomas Mraz <tmraz@fedoraproject.org> (Merged from https://github.com/openssl/openssl/pull/10669)
2019-12-20 06:30:24 +08:00
The STACK_OF() macro returns the name for a stack of the specified B<I<TYPE>>.
This is an opaque pointer to a structure declaration.
This can be used in every header file that references the stack.
There are several B<DEFINE...> macros that create static inline functions
for all of the functions described on this page.
This should normally be used in one source file, and the stack manipulation
is wrapped with application-specific functions.
DEFINE_STACK_OF() creates set of functions for a stack of B<I<TYPE>> elements.
The type is referenced by
Make manuals with TYPE conform with man-pages(7) Details from man-pages(7) that are used: Formatting conventions for manual pages describing functions ... Variable names should, like argument names, be specified in italics. ... Formatting conventions (general) ... Special macros, which are usually in uppercase, are in bold. Exception: don't boldface NULL. ... Furthermore, for TYPE used as a placeholder for types and correponding part of function names, we extrapolate that it's both a type and a variable, and should therefore be bold (typical for types and function names) and italic (typical for variables). POD processors don'e know this, so we have to help them along. Therefore: SPARSE_ARRAY_OF(TYPE) => B<SPARSE_ARRAY_OF>(B<I<TYPE>>) ossl_sa_TYPE_num() => B<ossl_sa_I<TYPE>_num>() TYPE => B<I<TYPE>> There are some other less typical uses where one simply has to give formatting some extra though. Reviewed-by: Matt Caswell <matt@openssl.org> (Merged from https://github.com/openssl/openssl/pull/10041)
2019-09-28 13:33:38 +08:00
B<STACK_OF>(B<I<TYPE>>) and each function name begins with B<sk_I<TYPE>_>.
Replace all #define's in pod pages. Function-like macros are replaced with prototypes and a note that they are implemented as macros. Constants are just referenced in-line in the text. Tweak BIO_TYPE_... documentation. Also fix RT4592. Reviewed-by: Matt Caswell <matt@openssl.org>
2016-07-09 00:55:45 +08:00
DEFINE_STACK_OF_CONST() is identical to DEFINE_STACK_OF() except
In OpenSSL builds, declare STACK for datatypes ... ... and only *define* them in the source files that need them. Use DEFINE_OR_DECLARE which is set appropriately for internal builds and not non-deprecated builds. Deprecate stack-of-block Better documentation Move some ASN1 struct typedefs to types.h Update ParseC to handle this. Most of all, ParseC needed to be more consistent. The handlers are "recursive", in so far that they are called again and again until they terminate, which depends entirely on what the "massager" returns. There's a comment at the beginning of ParseC that explains how that works. {Richard Levtte} Reviewed-by: Dmitry Belyavskiy <beldmit@gmail.com> Reviewed-by: Tomas Mraz <tmraz@fedoraproject.org> (Merged from https://github.com/openssl/openssl/pull/10669)
2019-12-20 06:30:24 +08:00
each element is constant.
Rename lh_xxx,sk_xxx tp OPENSSL_{LH,SK}_xxx Rename sk_xxx to OPENSSL_sk_xxx and _STACK to OPENSSL_STACK Rename lh_xxx API to OPENSSL_LH_xxx and LHASH_NODE to OPENSSL_LH_NODE Make lhash stuff opaque. Use typedefs for function pointers; makes the code simpler. Remove CHECKED_xxx macros. Add documentation; remove old X509-oriented doc. Add API-compat names for entire old API Reviewed-by: Dr. Stephen Henson <steve@openssl.org>
2016-05-20 22:46:29 +08:00
In OpenSSL builds, declare STACK for datatypes ... ... and only *define* them in the source files that need them. Use DEFINE_OR_DECLARE which is set appropriately for internal builds and not non-deprecated builds. Deprecate stack-of-block Better documentation Move some ASN1 struct typedefs to types.h Update ParseC to handle this. Most of all, ParseC needed to be more consistent. The handlers are "recursive", in so far that they are called again and again until they terminate, which depends entirely on what the "massager" returns. There's a comment at the beginning of ParseC that explains how that works. {Richard Levtte} Reviewed-by: Dmitry Belyavskiy <beldmit@gmail.com> Reviewed-by: Tomas Mraz <tmraz@fedoraproject.org> (Merged from https://github.com/openssl/openssl/pull/10669)
2019-12-20 06:30:24 +08:00
/* DEFINE_STACK_OF(TYPE) */
TYPE *sk_TYPE_value(STACK_OF(TYPE) *sk, int idx);
/* DEFINE_STACK_OF_CONST(TYPE) */
Rename lh_xxx,sk_xxx tp OPENSSL_{LH,SK}_xxx Rename sk_xxx to OPENSSL_sk_xxx and _STACK to OPENSSL_STACK Rename lh_xxx API to OPENSSL_LH_xxx and LHASH_NODE to OPENSSL_LH_NODE Make lhash stuff opaque. Use typedefs for function pointers; makes the code simpler. Remove CHECKED_xxx macros. Add documentation; remove old X509-oriented doc. Add API-compat names for entire old API Reviewed-by: Dr. Stephen Henson <steve@openssl.org>
2016-05-20 22:46:29 +08:00
const TYPE *sk_TYPE_value(STACK_OF(TYPE) *sk, int idx);
In OpenSSL builds, declare STACK for datatypes ... ... and only *define* them in the source files that need them. Use DEFINE_OR_DECLARE which is set appropriately for internal builds and not non-deprecated builds. Deprecate stack-of-block Better documentation Move some ASN1 struct typedefs to types.h Update ParseC to handle this. Most of all, ParseC needed to be more consistent. The handlers are "recursive", in so far that they are called again and again until they terminate, which depends entirely on what the "massager" returns. There's a comment at the beginning of ParseC that explains how that works. {Richard Levtte} Reviewed-by: Dmitry Belyavskiy <beldmit@gmail.com> Reviewed-by: Tomas Mraz <tmraz@fedoraproject.org> (Merged from https://github.com/openssl/openssl/pull/10669)
2019-12-20 06:30:24 +08:00
DEFINE_SPECIAL_STACK_OF() and DEFINE_SPECIAL_STACK_OF_CONST() are similar
except B<FUNCNAME> is used in the function names:
Rename lh_xxx,sk_xxx tp OPENSSL_{LH,SK}_xxx Rename sk_xxx to OPENSSL_sk_xxx and _STACK to OPENSSL_STACK Rename lh_xxx API to OPENSSL_LH_xxx and LHASH_NODE to OPENSSL_LH_NODE Make lhash stuff opaque. Use typedefs for function pointers; makes the code simpler. Remove CHECKED_xxx macros. Add documentation; remove old X509-oriented doc. Add API-compat names for entire old API Reviewed-by: Dr. Stephen Henson <steve@openssl.org>
2016-05-20 22:46:29 +08:00
In OpenSSL builds, declare STACK for datatypes ... ... and only *define* them in the source files that need them. Use DEFINE_OR_DECLARE which is set appropriately for internal builds and not non-deprecated builds. Deprecate stack-of-block Better documentation Move some ASN1 struct typedefs to types.h Update ParseC to handle this. Most of all, ParseC needed to be more consistent. The handlers are "recursive", in so far that they are called again and again until they terminate, which depends entirely on what the "massager" returns. There's a comment at the beginning of ParseC that explains how that works. {Richard Levtte} Reviewed-by: Dmitry Belyavskiy <beldmit@gmail.com> Reviewed-by: Tomas Mraz <tmraz@fedoraproject.org> (Merged from https://github.com/openssl/openssl/pull/10669)
2019-12-20 06:30:24 +08:00
/* DEFINE_SPECIAL_STACK_OF(TYPE, FUNCNAME) */
Rename lh_xxx,sk_xxx tp OPENSSL_{LH,SK}_xxx Rename sk_xxx to OPENSSL_sk_xxx and _STACK to OPENSSL_STACK Rename lh_xxx API to OPENSSL_LH_xxx and LHASH_NODE to OPENSSL_LH_NODE Make lhash stuff opaque. Use typedefs for function pointers; makes the code simpler. Remove CHECKED_xxx macros. Add documentation; remove old X509-oriented doc. Add API-compat names for entire old API Reviewed-by: Dr. Stephen Henson <steve@openssl.org>
2016-05-20 22:46:29 +08:00
TYPE *sk_FUNCNAME_value(STACK_OF(TYPE) *sk, int idx);
In OpenSSL builds, declare STACK for datatypes ... ... and only *define* them in the source files that need them. Use DEFINE_OR_DECLARE which is set appropriately for internal builds and not non-deprecated builds. Deprecate stack-of-block Better documentation Move some ASN1 struct typedefs to types.h Update ParseC to handle this. Most of all, ParseC needed to be more consistent. The handlers are "recursive", in so far that they are called again and again until they terminate, which depends entirely on what the "massager" returns. There's a comment at the beginning of ParseC that explains how that works. {Richard Levtte} Reviewed-by: Dmitry Belyavskiy <beldmit@gmail.com> Reviewed-by: Tomas Mraz <tmraz@fedoraproject.org> (Merged from https://github.com/openssl/openssl/pull/10669)
2019-12-20 06:30:24 +08:00
/* DEFINE_SPECIAL_STACK_OF(TYPE, FUNCNAME) */
Replace all #define's in pod pages. Function-like macros are replaced with prototypes and a note that they are implemented as macros. Constants are just referenced in-line in the text. Tweak BIO_TYPE_... documentation. Also fix RT4592. Reviewed-by: Matt Caswell <matt@openssl.org>
2016-07-09 00:55:45 +08:00
const TYPE *sk_FUNCNAME_value(STACK_OF(TYPE) *sk, int idx);
Make manuals with TYPE conform with man-pages(7) Details from man-pages(7) that are used: Formatting conventions for manual pages describing functions ... Variable names should, like argument names, be specified in italics. ... Formatting conventions (general) ... Special macros, which are usually in uppercase, are in bold. Exception: don't boldface NULL. ... Furthermore, for TYPE used as a placeholder for types and correponding part of function names, we extrapolate that it's both a type and a variable, and should therefore be bold (typical for types and function names) and italic (typical for variables). POD processors don'e know this, so we have to help them along. Therefore: SPARSE_ARRAY_OF(TYPE) => B<SPARSE_ARRAY_OF>(B<I<TYPE>>) ossl_sa_TYPE_num() => B<ossl_sa_I<TYPE>_num>() TYPE => B<I<TYPE>> There are some other less typical uses where one simply has to give formatting some extra though. Reviewed-by: Matt Caswell <matt@openssl.org> (Merged from https://github.com/openssl/openssl/pull/10041)
2019-09-28 13:33:38 +08:00
B<sk_I<TYPE>_num>() returns the number of elements in I<sk> or -1 if I<sk> is
NULL.
Rename lh_xxx,sk_xxx tp OPENSSL_{LH,SK}_xxx Rename sk_xxx to OPENSSL_sk_xxx and _STACK to OPENSSL_STACK Rename lh_xxx API to OPENSSL_LH_xxx and LHASH_NODE to OPENSSL_LH_NODE Make lhash stuff opaque. Use typedefs for function pointers; makes the code simpler. Remove CHECKED_xxx macros. Add documentation; remove old X509-oriented doc. Add API-compat names for entire old API Reviewed-by: Dr. Stephen Henson <steve@openssl.org>
2016-05-20 22:46:29 +08:00
Make manuals with TYPE conform with man-pages(7) Details from man-pages(7) that are used: Formatting conventions for manual pages describing functions ... Variable names should, like argument names, be specified in italics. ... Formatting conventions (general) ... Special macros, which are usually in uppercase, are in bold. Exception: don't boldface NULL. ... Furthermore, for TYPE used as a placeholder for types and correponding part of function names, we extrapolate that it's both a type and a variable, and should therefore be bold (typical for types and function names) and italic (typical for variables). POD processors don'e know this, so we have to help them along. Therefore: SPARSE_ARRAY_OF(TYPE) => B<SPARSE_ARRAY_OF>(B<I<TYPE>>) ossl_sa_TYPE_num() => B<ossl_sa_I<TYPE>_num>() TYPE => B<I<TYPE>> There are some other less typical uses where one simply has to give formatting some extra though. Reviewed-by: Matt Caswell <matt@openssl.org> (Merged from https://github.com/openssl/openssl/pull/10041)
2019-09-28 13:33:38 +08:00
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.
Rename lh_xxx,sk_xxx tp OPENSSL_{LH,SK}_xxx Rename sk_xxx to OPENSSL_sk_xxx and _STACK to OPENSSL_STACK Rename lh_xxx API to OPENSSL_LH_xxx and LHASH_NODE to OPENSSL_LH_NODE Make lhash stuff opaque. Use typedefs for function pointers; makes the code simpler. Remove CHECKED_xxx macros. Add documentation; remove old X509-oriented doc. Add API-compat names for entire old API Reviewed-by: Dr. Stephen Henson <steve@openssl.org>
2016-05-20 22:46:29 +08:00
Make manuals with TYPE conform with man-pages(7) Details from man-pages(7) that are used: Formatting conventions for manual pages describing functions ... Variable names should, like argument names, be specified in italics. ... Formatting conventions (general) ... Special macros, which are usually in uppercase, are in bold. Exception: don't boldface NULL. ... Furthermore, for TYPE used as a placeholder for types and correponding part of function names, we extrapolate that it's both a type and a variable, and should therefore be bold (typical for types and function names) and italic (typical for variables). POD processors don'e know this, so we have to help them along. Therefore: SPARSE_ARRAY_OF(TYPE) => B<SPARSE_ARRAY_OF>(B<I<TYPE>>) ossl_sa_TYPE_num() => B<ossl_sa_I<TYPE>_num>() TYPE => B<I<TYPE>> There are some other less typical uses where one simply has to give formatting some extra though. Reviewed-by: Matt Caswell <matt@openssl.org> (Merged from https://github.com/openssl/openssl/pull/10041)
2019-09-28 13:33:38 +08:00
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).
Rename lh_xxx,sk_xxx tp OPENSSL_{LH,SK}_xxx Rename sk_xxx to OPENSSL_sk_xxx and _STACK to OPENSSL_STACK Rename lh_xxx API to OPENSSL_LH_xxx and LHASH_NODE to OPENSSL_LH_NODE Make lhash stuff opaque. Use typedefs for function pointers; makes the code simpler. Remove CHECKED_xxx macros. Add documentation; remove old X509-oriented doc. Add API-compat names for entire old API Reviewed-by: Dr. Stephen Henson <steve@openssl.org>
2016-05-20 22:46:29 +08:00
Make manuals with TYPE conform with man-pages(7) Details from man-pages(7) that are used: Formatting conventions for manual pages describing functions ... Variable names should, like argument names, be specified in italics. ... Formatting conventions (general) ... Special macros, which are usually in uppercase, are in bold. Exception: don't boldface NULL. ... Furthermore, for TYPE used as a placeholder for types and correponding part of function names, we extrapolate that it's both a type and a variable, and should therefore be bold (typical for types and function names) and italic (typical for variables). POD processors don'e know this, so we have to help them along. Therefore: SPARSE_ARRAY_OF(TYPE) => B<SPARSE_ARRAY_OF>(B<I<TYPE>>) ossl_sa_TYPE_num() => B<ossl_sa_I<TYPE>_num>() TYPE => B<I<TYPE>> There are some other less typical uses where one simply has to give formatting some extra though. Reviewed-by: Matt Caswell <matt@openssl.org> (Merged from https://github.com/openssl/openssl/pull/10041)
2019-09-28 13:33:38 +08:00
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).
Rename lh_xxx,sk_xxx tp OPENSSL_{LH,SK}_xxx Rename sk_xxx to OPENSSL_sk_xxx and _STACK to OPENSSL_STACK Rename lh_xxx API to OPENSSL_LH_xxx and LHASH_NODE to OPENSSL_LH_NODE Make lhash stuff opaque. Use typedefs for function pointers; makes the code simpler. Remove CHECKED_xxx macros. Add documentation; remove old X509-oriented doc. Add API-compat names for entire old API Reviewed-by: Dr. Stephen Henson <steve@openssl.org>
2016-05-20 22:46:29 +08:00
Make manuals with TYPE conform with man-pages(7) Details from man-pages(7) that are used: Formatting conventions for manual pages describing functions ... Variable names should, like argument names, be specified in italics. ... Formatting conventions (general) ... Special macros, which are usually in uppercase, are in bold. Exception: don't boldface NULL. ... Furthermore, for TYPE used as a placeholder for types and correponding part of function names, we extrapolate that it's both a type and a variable, and should therefore be bold (typical for types and function names) and italic (typical for variables). POD processors don'e know this, so we have to help them along. Therefore: SPARSE_ARRAY_OF(TYPE) => B<SPARSE_ARRAY_OF>(B<I<TYPE>>) ossl_sa_TYPE_num() => B<ossl_sa_I<TYPE>_num>() TYPE => B<I<TYPE>> There are some other less typical uses where one simply has to give formatting some extra though. Reviewed-by: Matt Caswell <matt@openssl.org> (Merged from https://github.com/openssl/openssl/pull/10041)
2019-09-28 13:33:38 +08:00
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.
Add a reserve call to the stack data structure. This allows the caller to guarantee that there is sufficient space for a number of insertions without reallocation. The expansion ratio when reallocating the array is reduced to 1.5 rather than 2. Change bounds testing to use a single size rather than both INT_MAX and SIZE_MAX. This simplifies some of the tests. Switch the stack pointers to data from char * to void * Reviewed-by: Andy Polyakov <appro@openssl.org> (Merged from https://github.com/openssl/openssl/pull/4386)
2017-08-17 08:10:07 +08:00
Make manuals with TYPE conform with man-pages(7) Details from man-pages(7) that are used: Formatting conventions for manual pages describing functions ... Variable names should, like argument names, be specified in italics. ... Formatting conventions (general) ... Special macros, which are usually in uppercase, are in bold. Exception: don't boldface NULL. ... Furthermore, for TYPE used as a placeholder for types and correponding part of function names, we extrapolate that it's both a type and a variable, and should therefore be bold (typical for types and function names) and italic (typical for variables). POD processors don'e know this, so we have to help them along. Therefore: SPARSE_ARRAY_OF(TYPE) => B<SPARSE_ARRAY_OF>(B<I<TYPE>>) ossl_sa_TYPE_num() => B<ossl_sa_I<TYPE>_num>() TYPE => B<I<TYPE>> There are some other less typical uses where one simply has to give formatting some extra though. Reviewed-by: Matt Caswell <matt@openssl.org> (Merged from https://github.com/openssl/openssl/pull/10041)
2019-09-28 13:33:38 +08:00
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.
Add sk_TYPE_new_reserve() function This is a combination of sk_new and sk_reserve, to make it more convenient to allocate a new stack with reserved memory and comaprison function (if any). Reviewed-by: Paul Dale <paul.dale@oracle.com> Reviewed-by: Andy Polyakov <appro@openssl.org> Reviewed-by: Richard Levitte <levitte@openssl.org> (Merged from https://github.com/openssl/openssl/pull/4559)
2017-10-20 01:42:39 +08:00
Make manuals with TYPE conform with man-pages(7) Details from man-pages(7) that are used: Formatting conventions for manual pages describing functions ... Variable names should, like argument names, be specified in italics. ... Formatting conventions (general) ... Special macros, which are usually in uppercase, are in bold. Exception: don't boldface NULL. ... Furthermore, for TYPE used as a placeholder for types and correponding part of function names, we extrapolate that it's both a type and a variable, and should therefore be bold (typical for types and function names) and italic (typical for variables). POD processors don'e know this, so we have to help them along. Therefore: SPARSE_ARRAY_OF(TYPE) => B<SPARSE_ARRAY_OF>(B<I<TYPE>>) ossl_sa_TYPE_num() => B<ossl_sa_I<TYPE>_num>() TYPE => B<I<TYPE>> There are some other less typical uses where one simply has to give formatting some extra though. Reviewed-by: Matt Caswell <matt@openssl.org> (Merged from https://github.com/openssl/openssl/pull/10041)
2019-09-28 13:33:38 +08:00
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.
Rename lh_xxx,sk_xxx tp OPENSSL_{LH,SK}_xxx Rename sk_xxx to OPENSSL_sk_xxx and _STACK to OPENSSL_STACK Rename lh_xxx API to OPENSSL_LH_xxx and LHASH_NODE to OPENSSL_LH_NODE Make lhash stuff opaque. Use typedefs for function pointers; makes the code simpler. Remove CHECKED_xxx macros. Add documentation; remove old X509-oriented doc. Add API-compat names for entire old API Reviewed-by: Dr. Stephen Henson <steve@openssl.org>
2016-05-20 22:46:29 +08:00
Make manuals with TYPE conform with man-pages(7) Details from man-pages(7) that are used: Formatting conventions for manual pages describing functions ... Variable names should, like argument names, be specified in italics. ... Formatting conventions (general) ... Special macros, which are usually in uppercase, are in bold. Exception: don't boldface NULL. ... Furthermore, for TYPE used as a placeholder for types and correponding part of function names, we extrapolate that it's both a type and a variable, and should therefore be bold (typical for types and function names) and italic (typical for variables). POD processors don'e know this, so we have to help them along. Therefore: SPARSE_ARRAY_OF(TYPE) => B<SPARSE_ARRAY_OF>(B<I<TYPE>>) ossl_sa_TYPE_num() => B<ossl_sa_I<TYPE>_num>() TYPE => B<I<TYPE>> There are some other less typical uses where one simply has to give formatting some extra though. Reviewed-by: Matt Caswell <matt@openssl.org> (Merged from https://github.com/openssl/openssl/pull/10041)
2019-09-28 13:33:38 +08:00
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.
Rename lh_xxx,sk_xxx tp OPENSSL_{LH,SK}_xxx Rename sk_xxx to OPENSSL_sk_xxx and _STACK to OPENSSL_STACK Rename lh_xxx API to OPENSSL_LH_xxx and LHASH_NODE to OPENSSL_LH_NODE Make lhash stuff opaque. Use typedefs for function pointers; makes the code simpler. Remove CHECKED_xxx macros. Add documentation; remove old X509-oriented doc. Add API-compat names for entire old API Reviewed-by: Dr. Stephen Henson <steve@openssl.org>
2016-05-20 22:46:29 +08:00
Make manuals with TYPE conform with man-pages(7) Details from man-pages(7) that are used: Formatting conventions for manual pages describing functions ... Variable names should, like argument names, be specified in italics. ... Formatting conventions (general) ... Special macros, which are usually in uppercase, are in bold. Exception: don't boldface NULL. ... Furthermore, for TYPE used as a placeholder for types and correponding part of function names, we extrapolate that it's both a type and a variable, and should therefore be bold (typical for types and function names) and italic (typical for variables). POD processors don'e know this, so we have to help them along. Therefore: SPARSE_ARRAY_OF(TYPE) => B<SPARSE_ARRAY_OF>(B<I<TYPE>>) ossl_sa_TYPE_num() => B<ossl_sa_I<TYPE>_num>() TYPE => B<I<TYPE>> There are some other less typical uses where one simply has to give formatting some extra though. Reviewed-by: Matt Caswell <matt@openssl.org> (Merged from https://github.com/openssl/openssl/pull/10041)
2019-09-28 13:33:38 +08:00
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.
Rename lh_xxx,sk_xxx tp OPENSSL_{LH,SK}_xxx Rename sk_xxx to OPENSSL_sk_xxx and _STACK to OPENSSL_STACK Rename lh_xxx API to OPENSSL_LH_xxx and LHASH_NODE to OPENSSL_LH_NODE Make lhash stuff opaque. Use typedefs for function pointers; makes the code simpler. Remove CHECKED_xxx macros. Add documentation; remove old X509-oriented doc. Add API-compat names for entire old API Reviewed-by: Dr. Stephen Henson <steve@openssl.org>
2016-05-20 22:46:29 +08:00
Make manuals with TYPE conform with man-pages(7) Details from man-pages(7) that are used: Formatting conventions for manual pages describing functions ... Variable names should, like argument names, be specified in italics. ... Formatting conventions (general) ... Special macros, which are usually in uppercase, are in bold. Exception: don't boldface NULL. ... Furthermore, for TYPE used as a placeholder for types and correponding part of function names, we extrapolate that it's both a type and a variable, and should therefore be bold (typical for types and function names) and italic (typical for variables). POD processors don'e know this, so we have to help them along. Therefore: SPARSE_ARRAY_OF(TYPE) => B<SPARSE_ARRAY_OF>(B<I<TYPE>>) ossl_sa_TYPE_num() => B<ossl_sa_I<TYPE>_num>() TYPE => B<I<TYPE>> There are some other less typical uses where one simply has to give formatting some extra though. Reviewed-by: Matt Caswell <matt@openssl.org> (Merged from https://github.com/openssl/openssl/pull/10041)
2019-09-28 13:33:38 +08:00
B<sk_I<TYPE>_pop_free>() frees up all elements of I<sk> and I<sk> itself. The
Rename lh_xxx,sk_xxx tp OPENSSL_{LH,SK}_xxx Rename sk_xxx to OPENSSL_sk_xxx and _STACK to OPENSSL_STACK Rename lh_xxx API to OPENSSL_LH_xxx and LHASH_NODE to OPENSSL_LH_NODE Make lhash stuff opaque. Use typedefs for function pointers; makes the code simpler. Remove CHECKED_xxx macros. Add documentation; remove old X509-oriented doc. Add API-compat names for entire old API Reviewed-by: Dr. Stephen Henson <steve@openssl.org>
2016-05-20 22:46:29 +08:00
free function freefunc() is called on each element to free it.
Make manuals with TYPE conform with man-pages(7) Details from man-pages(7) that are used: Formatting conventions for manual pages describing functions ... Variable names should, like argument names, be specified in italics. ... Formatting conventions (general) ... Special macros, which are usually in uppercase, are in bold. Exception: don't boldface NULL. ... Furthermore, for TYPE used as a placeholder for types and correponding part of function names, we extrapolate that it's both a type and a variable, and should therefore be bold (typical for types and function names) and italic (typical for variables). POD processors don'e know this, so we have to help them along. Therefore: SPARSE_ARRAY_OF(TYPE) => B<SPARSE_ARRAY_OF>(B<I<TYPE>>) ossl_sa_TYPE_num() => B<ossl_sa_I<TYPE>_num>() TYPE => B<I<TYPE>> There are some other less typical uses where one simply has to give formatting some extra though. Reviewed-by: Matt Caswell <matt@openssl.org> (Merged from https://github.com/openssl/openssl/pull/10041)
2019-09-28 13:33:38 +08:00
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.
Rename lh_xxx,sk_xxx tp OPENSSL_{LH,SK}_xxx Rename sk_xxx to OPENSSL_sk_xxx and _STACK to OPENSSL_STACK Rename lh_xxx API to OPENSSL_LH_xxx and LHASH_NODE to OPENSSL_LH_NODE Make lhash stuff opaque. Use typedefs for function pointers; makes the code simpler. Remove CHECKED_xxx macros. Add documentation; remove old X509-oriented doc. Add API-compat names for entire old API Reviewed-by: Dr. Stephen Henson <steve@openssl.org>
2016-05-20 22:46:29 +08:00
Make manuals with TYPE conform with man-pages(7) Details from man-pages(7) that are used: Formatting conventions for manual pages describing functions ... Variable names should, like argument names, be specified in italics. ... Formatting conventions (general) ... Special macros, which are usually in uppercase, are in bold. Exception: don't boldface NULL. ... Furthermore, for TYPE used as a placeholder for types and correponding part of function names, we extrapolate that it's both a type and a variable, and should therefore be bold (typical for types and function names) and italic (typical for variables). POD processors don'e know this, so we have to help them along. Therefore: SPARSE_ARRAY_OF(TYPE) => B<SPARSE_ARRAY_OF>(B<I<TYPE>>) ossl_sa_TYPE_num() => B<ossl_sa_I<TYPE>_num>() TYPE => B<I<TYPE>> There are some other less typical uses where one simply has to give formatting some extra though. Reviewed-by: Matt Caswell <matt@openssl.org> (Merged from https://github.com/openssl/openssl/pull/10041)
2019-09-28 13:33:38 +08:00
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.
Rename lh_xxx,sk_xxx tp OPENSSL_{LH,SK}_xxx Rename sk_xxx to OPENSSL_sk_xxx and _STACK to OPENSSL_STACK Rename lh_xxx API to OPENSSL_LH_xxx and LHASH_NODE to OPENSSL_LH_NODE Make lhash stuff opaque. Use typedefs for function pointers; makes the code simpler. Remove CHECKED_xxx macros. Add documentation; remove old X509-oriented doc. Add API-compat names for entire old API Reviewed-by: Dr. Stephen Henson <steve@openssl.org>
2016-05-20 22:46:29 +08:00
Make manuals with TYPE conform with man-pages(7) Details from man-pages(7) that are used: Formatting conventions for manual pages describing functions ... Variable names should, like argument names, be specified in italics. ... Formatting conventions (general) ... Special macros, which are usually in uppercase, are in bold. Exception: don't boldface NULL. ... Furthermore, for TYPE used as a placeholder for types and correponding part of function names, we extrapolate that it's both a type and a variable, and should therefore be bold (typical for types and function names) and italic (typical for variables). POD processors don'e know this, so we have to help them along. Therefore: SPARSE_ARRAY_OF(TYPE) => B<SPARSE_ARRAY_OF>(B<I<TYPE>>) ossl_sa_TYPE_num() => B<ossl_sa_I<TYPE>_num>() TYPE => B<I<TYPE>> There are some other less typical uses where one simply has to give formatting some extra though. Reviewed-by: Matt Caswell <matt@openssl.org> (Merged from https://github.com/openssl/openssl/pull/10041)
2019-09-28 13:33:38 +08:00
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.
Rename lh_xxx,sk_xxx tp OPENSSL_{LH,SK}_xxx Rename sk_xxx to OPENSSL_sk_xxx and _STACK to OPENSSL_STACK Rename lh_xxx API to OPENSSL_LH_xxx and LHASH_NODE to OPENSSL_LH_NODE Make lhash stuff opaque. Use typedefs for function pointers; makes the code simpler. Remove CHECKED_xxx macros. Add documentation; remove old X509-oriented doc. Add API-compat names for entire old API Reviewed-by: Dr. Stephen Henson <steve@openssl.org>
2016-05-20 22:46:29 +08:00
Make manuals with TYPE conform with man-pages(7) Details from man-pages(7) that are used: Formatting conventions for manual pages describing functions ... Variable names should, like argument names, be specified in italics. ... Formatting conventions (general) ... Special macros, which are usually in uppercase, are in bold. Exception: don't boldface NULL. ... Furthermore, for TYPE used as a placeholder for types and correponding part of function names, we extrapolate that it's both a type and a variable, and should therefore be bold (typical for types and function names) and italic (typical for variables). POD processors don'e know this, so we have to help them along. Therefore: SPARSE_ARRAY_OF(TYPE) => B<SPARSE_ARRAY_OF>(B<I<TYPE>>) ossl_sa_TYPE_num() => B<ossl_sa_I<TYPE>_num>() TYPE => B<I<TYPE>> There are some other less typical uses where one simply has to give formatting some extra though. Reviewed-by: Matt Caswell <matt@openssl.org> (Merged from https://github.com/openssl/openssl/pull/10041)
2019-09-28 13:33:38 +08:00
B<sk_I<TYPE>_push>() appends I<ptr> to I<sk> it is equivalent to:
Rename lh_xxx,sk_xxx tp OPENSSL_{LH,SK}_xxx Rename sk_xxx to OPENSSL_sk_xxx and _STACK to OPENSSL_STACK Rename lh_xxx API to OPENSSL_LH_xxx and LHASH_NODE to OPENSSL_LH_NODE Make lhash stuff opaque. Use typedefs for function pointers; makes the code simpler. Remove CHECKED_xxx macros. Add documentation; remove old X509-oriented doc. Add API-compat names for entire old API Reviewed-by: Dr. Stephen Henson <steve@openssl.org>
2016-05-20 22:46:29 +08:00
sk_TYPE_insert(sk, ptr, -1);
Make manuals with TYPE conform with man-pages(7) Details from man-pages(7) that are used: Formatting conventions for manual pages describing functions ... Variable names should, like argument names, be specified in italics. ... Formatting conventions (general) ... Special macros, which are usually in uppercase, are in bold. Exception: don't boldface NULL. ... Furthermore, for TYPE used as a placeholder for types and correponding part of function names, we extrapolate that it's both a type and a variable, and should therefore be bold (typical for types and function names) and italic (typical for variables). POD processors don'e know this, so we have to help them along. Therefore: SPARSE_ARRAY_OF(TYPE) => B<SPARSE_ARRAY_OF>(B<I<TYPE>>) ossl_sa_TYPE_num() => B<ossl_sa_I<TYPE>_num>() TYPE => B<I<TYPE>> There are some other less typical uses where one simply has to give formatting some extra though. Reviewed-by: Matt Caswell <matt@openssl.org> (Merged from https://github.com/openssl/openssl/pull/10041)
2019-09-28 13:33:38 +08:00
B<sk_I<TYPE>_unshift>() inserts I<ptr> at the start of I<sk> it is equivalent
to:
Rename lh_xxx,sk_xxx tp OPENSSL_{LH,SK}_xxx Rename sk_xxx to OPENSSL_sk_xxx and _STACK to OPENSSL_STACK Rename lh_xxx API to OPENSSL_LH_xxx and LHASH_NODE to OPENSSL_LH_NODE Make lhash stuff opaque. Use typedefs for function pointers; makes the code simpler. Remove CHECKED_xxx macros. Add documentation; remove old X509-oriented doc. Add API-compat names for entire old API Reviewed-by: Dr. Stephen Henson <steve@openssl.org>
2016-05-20 22:46:29 +08:00
sk_TYPE_insert(sk, ptr, 0);
Make manuals with TYPE conform with man-pages(7) Details from man-pages(7) that are used: Formatting conventions for manual pages describing functions ... Variable names should, like argument names, be specified in italics. ... Formatting conventions (general) ... Special macros, which are usually in uppercase, are in bold. Exception: don't boldface NULL. ... Furthermore, for TYPE used as a placeholder for types and correponding part of function names, we extrapolate that it's both a type and a variable, and should therefore be bold (typical for types and function names) and italic (typical for variables). POD processors don'e know this, so we have to help them along. Therefore: SPARSE_ARRAY_OF(TYPE) => B<SPARSE_ARRAY_OF>(B<I<TYPE>>) ossl_sa_TYPE_num() => B<ossl_sa_I<TYPE>_num>() TYPE => B<I<TYPE>> There are some other less typical uses where one simply has to give formatting some extra though. Reviewed-by: Matt Caswell <matt@openssl.org> (Merged from https://github.com/openssl/openssl/pull/10041)
2019-09-28 13:33:38 +08:00
B<sk_I<TYPE>_pop>() returns and removes the last element from I<sk>.
Rename lh_xxx,sk_xxx tp OPENSSL_{LH,SK}_xxx Rename sk_xxx to OPENSSL_sk_xxx and _STACK to OPENSSL_STACK Rename lh_xxx API to OPENSSL_LH_xxx and LHASH_NODE to OPENSSL_LH_NODE Make lhash stuff opaque. Use typedefs for function pointers; makes the code simpler. Remove CHECKED_xxx macros. Add documentation; remove old X509-oriented doc. Add API-compat names for entire old API Reviewed-by: Dr. Stephen Henson <steve@openssl.org>
2016-05-20 22:46:29 +08:00
Make manuals with TYPE conform with man-pages(7) Details from man-pages(7) that are used: Formatting conventions for manual pages describing functions ... Variable names should, like argument names, be specified in italics. ... Formatting conventions (general) ... Special macros, which are usually in uppercase, are in bold. Exception: don't boldface NULL. ... Furthermore, for TYPE used as a placeholder for types and correponding part of function names, we extrapolate that it's both a type and a variable, and should therefore be bold (typical for types and function names) and italic (typical for variables). POD processors don'e know this, so we have to help them along. Therefore: SPARSE_ARRAY_OF(TYPE) => B<SPARSE_ARRAY_OF>(B<I<TYPE>>) ossl_sa_TYPE_num() => B<ossl_sa_I<TYPE>_num>() TYPE => B<I<TYPE>> There are some other less typical uses where one simply has to give formatting some extra though. Reviewed-by: Matt Caswell <matt@openssl.org> (Merged from https://github.com/openssl/openssl/pull/10041)
2019-09-28 13:33:38 +08:00
B<sk_I<TYPE>_shift>() returns and removes the first element from I<sk>.
Rename lh_xxx,sk_xxx tp OPENSSL_{LH,SK}_xxx Rename sk_xxx to OPENSSL_sk_xxx and _STACK to OPENSSL_STACK Rename lh_xxx API to OPENSSL_LH_xxx and LHASH_NODE to OPENSSL_LH_NODE Make lhash stuff opaque. Use typedefs for function pointers; makes the code simpler. Remove CHECKED_xxx macros. Add documentation; remove old X509-oriented doc. Add API-compat names for entire old API Reviewed-by: Dr. Stephen Henson <steve@openssl.org>
2016-05-20 22:46:29 +08:00
Make manuals with TYPE conform with man-pages(7) Details from man-pages(7) that are used: Formatting conventions for manual pages describing functions ... Variable names should, like argument names, be specified in italics. ... Formatting conventions (general) ... Special macros, which are usually in uppercase, are in bold. Exception: don't boldface NULL. ... Furthermore, for TYPE used as a placeholder for types and correponding part of function names, we extrapolate that it's both a type and a variable, and should therefore be bold (typical for types and function names) and italic (typical for variables). POD processors don'e know this, so we have to help them along. Therefore: SPARSE_ARRAY_OF(TYPE) => B<SPARSE_ARRAY_OF>(B<I<TYPE>>) ossl_sa_TYPE_num() => B<ossl_sa_I<TYPE>_num>() TYPE => B<I<TYPE>> There are some other less typical uses where one simply has to give formatting some extra though. Reviewed-by: Matt Caswell <matt@openssl.org> (Merged from https://github.com/openssl/openssl/pull/10041)
2019-09-28 13:33:38 +08:00
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.
Rename lh_xxx,sk_xxx tp OPENSSL_{LH,SK}_xxx Rename sk_xxx to OPENSSL_sk_xxx and _STACK to OPENSSL_STACK Rename lh_xxx API to OPENSSL_LH_xxx and LHASH_NODE to OPENSSL_LH_NODE Make lhash stuff opaque. Use typedefs for function pointers; makes the code simpler. Remove CHECKED_xxx macros. Add documentation; remove old X509-oriented doc. Add API-compat names for entire old API Reviewed-by: Dr. Stephen Henson <steve@openssl.org>
2016-05-20 22:46:29 +08:00
Make manuals with TYPE conform with man-pages(7) Details from man-pages(7) that are used: Formatting conventions for manual pages describing functions ... Variable names should, like argument names, be specified in italics. ... Formatting conventions (general) ... Special macros, which are usually in uppercase, are in bold. Exception: don't boldface NULL. ... Furthermore, for TYPE used as a placeholder for types and correponding part of function names, we extrapolate that it's both a type and a variable, and should therefore be bold (typical for types and function names) and italic (typical for variables). POD processors don'e know this, so we have to help them along. Therefore: SPARSE_ARRAY_OF(TYPE) => B<SPARSE_ARRAY_OF>(B<I<TYPE>>) ossl_sa_TYPE_num() => B<ossl_sa_I<TYPE>_num>() TYPE => B<I<TYPE>> There are some other less typical uses where one simply has to give formatting some extra though. Reviewed-by: Matt Caswell <matt@openssl.org> (Merged from https://github.com/openssl/openssl/pull/10041)
2019-09-28 13:33:38 +08:00
B<sk_I<TYPE>_find>() searches I<sk> for the element I<ptr>. In the case
Rewrite the documentation for sk_TYPE_find() and sk_TYPE_find_ex() to better describe the vagaries in their behaviour. [skip ci] Reviewed-by: Richard Levitte <levitte@openssl.org> Reviewed-by: Rich Salz <rsalz@openssl.org> (Merged from https://github.com/openssl/openssl/pull/2958)
2017-03-15 12:29:08 +08:00
where no comparison function has been specified, the function performs
Make manuals with TYPE conform with man-pages(7) Details from man-pages(7) that are used: Formatting conventions for manual pages describing functions ... Variable names should, like argument names, be specified in italics. ... Formatting conventions (general) ... Special macros, which are usually in uppercase, are in bold. Exception: don't boldface NULL. ... Furthermore, for TYPE used as a placeholder for types and correponding part of function names, we extrapolate that it's both a type and a variable, and should therefore be bold (typical for types and function names) and italic (typical for variables). POD processors don'e know this, so we have to help them along. Therefore: SPARSE_ARRAY_OF(TYPE) => B<SPARSE_ARRAY_OF>(B<I<TYPE>>) ossl_sa_TYPE_num() => B<ossl_sa_I<TYPE>_num>() TYPE => B<I<TYPE>> There are some other less typical uses where one simply has to give formatting some extra though. Reviewed-by: Matt Caswell <matt@openssl.org> (Merged from https://github.com/openssl/openssl/pull/10041)
2019-09-28 13:33:38 +08:00
a linear search for a pointer equal to I<ptr>. The index of the first
Rewrite the documentation for sk_TYPE_find() and sk_TYPE_find_ex() to better describe the vagaries in their behaviour. [skip ci] Reviewed-by: Richard Levitte <levitte@openssl.org> Reviewed-by: Rich Salz <rsalz@openssl.org> (Merged from https://github.com/openssl/openssl/pull/2958)
2017-03-15 12:29:08 +08:00
matching element is returned or B<-1> if there is no match. In the case
Improve the implementation of X509_STORE_CTX_get1_issuer() It is possible for the stack of X509_OBJECTs held in an X509_STORE_CTX to have a custom compare function associated with it. Normally (by default) this uses X509_NAME_cmp(). The X509_STORE_CTX_get1_issuer() function assumed that it would always be X509_NAME_cmp(). By implementing OPENSSL_sk_find_all() function we can avoid explicitly using X509_NAME_cmp() in X509_STORE_CTX_get1_issuer(). Reviewed-by: Matt Caswell <matt@openssl.org> (Merged from https://github.com/openssl/openssl/pull/14728)
2021-03-29 18:41:18 +08:00
where a comparison function has been specified, I<sk> is sorted and
Make manuals with TYPE conform with man-pages(7) Details from man-pages(7) that are used: Formatting conventions for manual pages describing functions ... Variable names should, like argument names, be specified in italics. ... Formatting conventions (general) ... Special macros, which are usually in uppercase, are in bold. Exception: don't boldface NULL. ... Furthermore, for TYPE used as a placeholder for types and correponding part of function names, we extrapolate that it's both a type and a variable, and should therefore be bold (typical for types and function names) and italic (typical for variables). POD processors don'e know this, so we have to help them along. Therefore: SPARSE_ARRAY_OF(TYPE) => B<SPARSE_ARRAY_OF>(B<I<TYPE>>) ossl_sa_TYPE_num() => B<ossl_sa_I<TYPE>_num>() TYPE => B<I<TYPE>> There are some other less typical uses where one simply has to give formatting some extra though. Reviewed-by: Matt Caswell <matt@openssl.org> (Merged from https://github.com/openssl/openssl/pull/10041)
2019-09-28 13:33:38 +08:00
B<sk_I<TYPE>_find>() returns the index of a matching element or B<-1> if there
Improve the implementation of X509_STORE_CTX_get1_issuer() It is possible for the stack of X509_OBJECTs held in an X509_STORE_CTX to have a custom compare function associated with it. Normally (by default) this uses X509_NAME_cmp(). The X509_STORE_CTX_get1_issuer() function assumed that it would always be X509_NAME_cmp(). By implementing OPENSSL_sk_find_all() function we can avoid explicitly using X509_NAME_cmp() in X509_STORE_CTX_get1_issuer(). Reviewed-by: Matt Caswell <matt@openssl.org> (Merged from https://github.com/openssl/openssl/pull/14728)
2021-03-29 18:41:18 +08:00
is no match. Note that, in this case the comparison function will usually
Rewrite the documentation for sk_TYPE_find() and sk_TYPE_find_ex() to better describe the vagaries in their behaviour. [skip ci] Reviewed-by: Richard Levitte <levitte@openssl.org> Reviewed-by: Rich Salz <rsalz@openssl.org> (Merged from https://github.com/openssl/openssl/pull/2958)
2017-03-15 12:29:08 +08:00
compare the values pointed to rather than the pointers themselves and
doc: note that the stack find functions no longer modify the stack Reviewed-by: Tomas Mraz <tomas@openssl.org> Reviewed-by: Todd Short <todd.short@me.com> (Merged from https://github.com/openssl/openssl/pull/20842)
2023-04-27 09:12:51 +08:00
the order of elements in I<sk> can change.
Rewrite the documentation for sk_TYPE_find() and sk_TYPE_find_ex() to better describe the vagaries in their behaviour. [skip ci] Reviewed-by: Richard Levitte <levitte@openssl.org> Reviewed-by: Rich Salz <rsalz@openssl.org> (Merged from https://github.com/openssl/openssl/pull/2958)
2017-03-15 12:29:08 +08:00
Make manuals with TYPE conform with man-pages(7) Details from man-pages(7) that are used: Formatting conventions for manual pages describing functions ... Variable names should, like argument names, be specified in italics. ... Formatting conventions (general) ... Special macros, which are usually in uppercase, are in bold. Exception: don't boldface NULL. ... Furthermore, for TYPE used as a placeholder for types and correponding part of function names, we extrapolate that it's both a type and a variable, and should therefore be bold (typical for types and function names) and italic (typical for variables). POD processors don'e know this, so we have to help them along. Therefore: SPARSE_ARRAY_OF(TYPE) => B<SPARSE_ARRAY_OF>(B<I<TYPE>>) ossl_sa_TYPE_num() => B<ossl_sa_I<TYPE>_num>() TYPE => B<I<TYPE>> There are some other less typical uses where one simply has to give formatting some extra though. Reviewed-by: Matt Caswell <matt@openssl.org> (Merged from https://github.com/openssl/openssl/pull/10041)
2019-09-28 13:33:38 +08:00
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
Improve the implementation of X509_STORE_CTX_get1_issuer() It is possible for the stack of X509_OBJECTs held in an X509_STORE_CTX to have a custom compare function associated with it. Normally (by default) this uses X509_NAME_cmp(). The X509_STORE_CTX_get1_issuer() function assumed that it would always be X509_NAME_cmp(). By implementing OPENSSL_sk_find_all() function we can avoid explicitly using X509_NAME_cmp() in X509_STORE_CTX_get1_issuer(). Reviewed-by: Matt Caswell <matt@openssl.org> (Merged from https://github.com/openssl/openssl/pull/14728)
2021-03-29 18:41:18 +08:00
present in I<sk>. The function also does not guarantee that the first matching
element in the sorted stack is returned.
B<sk_I<TYPE>_find_all>() operates like B<sk_I<TYPE>_find>() but it also
sets the I<*pnum> to number of matching elements in the stack. In case
no comparison function has been specified the I<*pnum> will be always set
to 1 if matching element was found, 0 otherwise.
Rename lh_xxx,sk_xxx tp OPENSSL_{LH,SK}_xxx Rename sk_xxx to OPENSSL_sk_xxx and _STACK to OPENSSL_STACK Rename lh_xxx API to OPENSSL_LH_xxx and LHASH_NODE to OPENSSL_LH_NODE Make lhash stuff opaque. Use typedefs for function pointers; makes the code simpler. Remove CHECKED_xxx macros. Add documentation; remove old X509-oriented doc. Add API-compat names for entire old API Reviewed-by: Dr. Stephen Henson <steve@openssl.org>
2016-05-20 22:46:29 +08:00
Make manuals with TYPE conform with man-pages(7) Details from man-pages(7) that are used: Formatting conventions for manual pages describing functions ... Variable names should, like argument names, be specified in italics. ... Formatting conventions (general) ... Special macros, which are usually in uppercase, are in bold. Exception: don't boldface NULL. ... Furthermore, for TYPE used as a placeholder for types and correponding part of function names, we extrapolate that it's both a type and a variable, and should therefore be bold (typical for types and function names) and italic (typical for variables). POD processors don'e know this, so we have to help them along. Therefore: SPARSE_ARRAY_OF(TYPE) => B<SPARSE_ARRAY_OF>(B<I<TYPE>>) ossl_sa_TYPE_num() => B<ossl_sa_I<TYPE>_num>() TYPE => B<I<TYPE>> There are some other less typical uses where one simply has to give formatting some extra though. Reviewed-by: Matt Caswell <matt@openssl.org> (Merged from https://github.com/openssl/openssl/pull/10041)
2019-09-28 13:33:38 +08:00
B<sk_I<TYPE>_sort>() sorts I<sk> using the supplied comparison function.
Rename lh_xxx,sk_xxx tp OPENSSL_{LH,SK}_xxx Rename sk_xxx to OPENSSL_sk_xxx and _STACK to OPENSSL_STACK Rename lh_xxx API to OPENSSL_LH_xxx and LHASH_NODE to OPENSSL_LH_NODE Make lhash stuff opaque. Use typedefs for function pointers; makes the code simpler. Remove CHECKED_xxx macros. Add documentation; remove old X509-oriented doc. Add API-compat names for entire old API Reviewed-by: Dr. Stephen Henson <steve@openssl.org>
2016-05-20 22:46:29 +08:00
Make manuals with TYPE conform with man-pages(7) Details from man-pages(7) that are used: Formatting conventions for manual pages describing functions ... Variable names should, like argument names, be specified in italics. ... Formatting conventions (general) ... Special macros, which are usually in uppercase, are in bold. Exception: don't boldface NULL. ... Furthermore, for TYPE used as a placeholder for types and correponding part of function names, we extrapolate that it's both a type and a variable, and should therefore be bold (typical for types and function names) and italic (typical for variables). POD processors don'e know this, so we have to help them along. Therefore: SPARSE_ARRAY_OF(TYPE) => B<SPARSE_ARRAY_OF>(B<I<TYPE>>) ossl_sa_TYPE_num() => B<ossl_sa_I<TYPE>_num>() TYPE => B<I<TYPE>> There are some other less typical uses where one simply has to give formatting some extra though. Reviewed-by: Matt Caswell <matt@openssl.org> (Merged from https://github.com/openssl/openssl/pull/10041)
2019-09-28 13:33:38 +08:00
B<sk_I<TYPE>_is_sorted>() returns B<1> if I<sk> is sorted and B<0> otherwise.
Rename lh_xxx,sk_xxx tp OPENSSL_{LH,SK}_xxx Rename sk_xxx to OPENSSL_sk_xxx and _STACK to OPENSSL_STACK Rename lh_xxx API to OPENSSL_LH_xxx and LHASH_NODE to OPENSSL_LH_NODE Make lhash stuff opaque. Use typedefs for function pointers; makes the code simpler. Remove CHECKED_xxx macros. Add documentation; remove old X509-oriented doc. Add API-compat names for entire old API Reviewed-by: Dr. Stephen Henson <steve@openssl.org>
2016-05-20 22:46:29 +08:00
Allow NULL arg to OPENSSL_sk_{dup,deep_copy} returning empty stack This simplifies many usages Reviewed-by: Tomas Mraz <tomas@openssl.org> (Merged from https://github.com/openssl/openssl/pull/14040)
2020-12-24 02:33:03 +08:00
B<sk_I<TYPE>_dup>() returns a shallow copy of I<sk>
or an empty stack if the passed stack is NULL.
Note the pointers in the copy are identical to the original.
Rename lh_xxx,sk_xxx tp OPENSSL_{LH,SK}_xxx Rename sk_xxx to OPENSSL_sk_xxx and _STACK to OPENSSL_STACK Rename lh_xxx API to OPENSSL_LH_xxx and LHASH_NODE to OPENSSL_LH_NODE Make lhash stuff opaque. Use typedefs for function pointers; makes the code simpler. Remove CHECKED_xxx macros. Add documentation; remove old X509-oriented doc. Add API-compat names for entire old API Reviewed-by: Dr. Stephen Henson <steve@openssl.org>
2016-05-20 22:46:29 +08:00
Make manuals with TYPE conform with man-pages(7) Details from man-pages(7) that are used: Formatting conventions for manual pages describing functions ... Variable names should, like argument names, be specified in italics. ... Formatting conventions (general) ... Special macros, which are usually in uppercase, are in bold. Exception: don't boldface NULL. ... Furthermore, for TYPE used as a placeholder for types and correponding part of function names, we extrapolate that it's both a type and a variable, and should therefore be bold (typical for types and function names) and italic (typical for variables). POD processors don'e know this, so we have to help them along. Therefore: SPARSE_ARRAY_OF(TYPE) => B<SPARSE_ARRAY_OF>(B<I<TYPE>>) ossl_sa_TYPE_num() => B<ossl_sa_I<TYPE>_num>() TYPE => B<I<TYPE>> There are some other less typical uses where one simply has to give formatting some extra though. Reviewed-by: Matt Caswell <matt@openssl.org> (Merged from https://github.com/openssl/openssl/pull/10041)
2019-09-28 13:33:38 +08:00
B<sk_I<TYPE>_deep_copy>() returns a new stack where each element has been
Allow NULL arg to OPENSSL_sk_{dup,deep_copy} returning empty stack This simplifies many usages Reviewed-by: Tomas Mraz <tomas@openssl.org> (Merged from https://github.com/openssl/openssl/pull/14040)
2020-12-24 02:33:03 +08:00
copied or an empty stack if the passed stack is NULL.
Copying is performed by the supplied copyfunc() and freeing by freefunc().
The function freefunc() is only called if an error occurs.
Rename lh_xxx,sk_xxx tp OPENSSL_{LH,SK}_xxx Rename sk_xxx to OPENSSL_sk_xxx and _STACK to OPENSSL_STACK Rename lh_xxx API to OPENSSL_LH_xxx and LHASH_NODE to OPENSSL_LH_NODE Make lhash stuff opaque. Use typedefs for function pointers; makes the code simpler. Remove CHECKED_xxx macros. Add documentation; remove old X509-oriented doc. Add API-compat names for entire old API Reviewed-by: Dr. Stephen Henson <steve@openssl.org>
2016-05-20 22:46:29 +08:00
=head1 NOTES
Care should be taken when accessing stacks in multi-threaded environments.
Make manuals with TYPE conform with man-pages(7) Details from man-pages(7) that are used: Formatting conventions for manual pages describing functions ... Variable names should, like argument names, be specified in italics. ... Formatting conventions (general) ... Special macros, which are usually in uppercase, are in bold. Exception: don't boldface NULL. ... Furthermore, for TYPE used as a placeholder for types and correponding part of function names, we extrapolate that it's both a type and a variable, and should therefore be bold (typical for types and function names) and italic (typical for variables). POD processors don'e know this, so we have to help them along. Therefore: SPARSE_ARRAY_OF(TYPE) => B<SPARSE_ARRAY_OF>(B<I<TYPE>>) ossl_sa_TYPE_num() => B<ossl_sa_I<TYPE>_num>() TYPE => B<I<TYPE>> There are some other less typical uses where one simply has to give formatting some extra though. Reviewed-by: Matt Caswell <matt@openssl.org> (Merged from https://github.com/openssl/openssl/pull/10041)
2019-09-28 13:33:38 +08:00
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.
Rename lh_xxx,sk_xxx tp OPENSSL_{LH,SK}_xxx Rename sk_xxx to OPENSSL_sk_xxx and _STACK to OPENSSL_STACK Rename lh_xxx API to OPENSSL_LH_xxx and LHASH_NODE to OPENSSL_LH_NODE Make lhash stuff opaque. Use typedefs for function pointers; makes the code simpler. Remove CHECKED_xxx macros. Add documentation; remove old X509-oriented doc. Add API-compat names for entire old API Reviewed-by: Dr. Stephen Henson <steve@openssl.org>
2016-05-20 22:46:29 +08:00
Any comparison function supplied should use a metric suitable
for use in a binary search operation. That is it should return zero, a
Make manuals with TYPE conform with man-pages(7) Details from man-pages(7) that are used: Formatting conventions for manual pages describing functions ... Variable names should, like argument names, be specified in italics. ... Formatting conventions (general) ... Special macros, which are usually in uppercase, are in bold. Exception: don't boldface NULL. ... Furthermore, for TYPE used as a placeholder for types and correponding part of function names, we extrapolate that it's both a type and a variable, and should therefore be bold (typical for types and function names) and italic (typical for variables). POD processors don'e know this, so we have to help them along. Therefore: SPARSE_ARRAY_OF(TYPE) => B<SPARSE_ARRAY_OF>(B<I<TYPE>>) ossl_sa_TYPE_num() => B<ossl_sa_I<TYPE>_num>() TYPE => B<I<TYPE>> There are some other less typical uses where one simply has to give formatting some extra though. Reviewed-by: Matt Caswell <matt@openssl.org> (Merged from https://github.com/openssl/openssl/pull/10041)
2019-09-28 13:33:38 +08:00
positive or negative value if I<a> is equal to, greater than
or less than I<b> respectively.
Rename lh_xxx,sk_xxx tp OPENSSL_{LH,SK}_xxx Rename sk_xxx to OPENSSL_sk_xxx and _STACK to OPENSSL_STACK Rename lh_xxx API to OPENSSL_LH_xxx and LHASH_NODE to OPENSSL_LH_NODE Make lhash stuff opaque. Use typedefs for function pointers; makes the code simpler. Remove CHECKED_xxx macros. Add documentation; remove old X509-oriented doc. Add API-compat names for entire old API Reviewed-by: Dr. Stephen Henson <steve@openssl.org>
2016-05-20 22:46:29 +08:00
Care should be taken when checking the return values of the functions
Make manuals with TYPE conform with man-pages(7) Details from man-pages(7) that are used: Formatting conventions for manual pages describing functions ... Variable names should, like argument names, be specified in italics. ... Formatting conventions (general) ... Special macros, which are usually in uppercase, are in bold. Exception: don't boldface NULL. ... Furthermore, for TYPE used as a placeholder for types and correponding part of function names, we extrapolate that it's both a type and a variable, and should therefore be bold (typical for types and function names) and italic (typical for variables). POD processors don'e know this, so we have to help them along. Therefore: SPARSE_ARRAY_OF(TYPE) => B<SPARSE_ARRAY_OF>(B<I<TYPE>>) ossl_sa_TYPE_num() => B<ossl_sa_I<TYPE>_num>() TYPE => B<I<TYPE>> There are some other less typical uses where one simply has to give formatting some extra though. Reviewed-by: Matt Caswell <matt@openssl.org> (Merged from https://github.com/openssl/openssl/pull/10041)
2019-09-28 13:33:38 +08:00
B<sk_I<TYPE>_find>() and B<sk_I<TYPE>_find_ex>(). They return an index to the
Rename lh_xxx,sk_xxx tp OPENSSL_{LH,SK}_xxx Rename sk_xxx to OPENSSL_sk_xxx and _STACK to OPENSSL_STACK Rename lh_xxx API to OPENSSL_LH_xxx and LHASH_NODE to OPENSSL_LH_NODE Make lhash stuff opaque. Use typedefs for function pointers; makes the code simpler. Remove CHECKED_xxx macros. Add documentation; remove old X509-oriented doc. Add API-compat names for entire old API Reviewed-by: Dr. Stephen Henson <steve@openssl.org>
2016-05-20 22:46:29 +08:00
matching element. In particular B<0> indicates a matching first element.
A failed search is indicated by a B<-1> return value.
Replace all #define's in pod pages. Function-like macros are replaced with prototypes and a note that they are implemented as macros. Constants are just referenced in-line in the text. Tweak BIO_TYPE_... documentation. Also fix RT4592. Reviewed-by: Matt Caswell <matt@openssl.org>
2016-07-09 00:55:45 +08:00
STACK_OF(), DEFINE_STACK_OF(), DEFINE_STACK_OF_CONST(), and
DEFINE_SPECIAL_STACK_OF() are implemented as macros.
Document the stack functions that are forgiving I.e., those that can be called with NULL stack parameter or invalid index. Reviewed-by: Todd Short <todd.short@me.com> Reviewed-by: Paul Dale <pauli@openssl.org> (Merged from https://github.com/openssl/openssl/pull/19400)
2022-10-13 17:39:35 +08:00
It is not an error to call B<sk_I<TYPE>_num>(), B<sk_I<TYPE>_value>(),
B<sk_I<TYPE>_free>(), B<sk_I<TYPE>_zero>(), B<sk_I<TYPE>_pop_free>(),
B<sk_I<TYPE>_delete>(), B<sk_I<TYPE>_delete_ptr>(), B<sk_I<TYPE>_pop>(),
B<sk_I<TYPE>_shift>(), B<sk_I<TYPE>_find>(), B<sk_I<TYPE>_find_ex>(),
and B<sk_I<TYPE>_find_all>() on a NULL stack, empty stack, or with
an invalid index. An error is not raised in these conditions.
Use safestack.h exclusively internally. Remove all stack headers from some includes that don't use them. Avoid a genearic untyped stack use. Update stack POD file to include the OPENSSL_sk_ API functions in the notes section. They were mentioned in the name section but not defined anywhere. Reviewed-by: Richard Levitte <levitte@openssl.org> (Merged from https://github.com/openssl/openssl/pull/4430)
2017-09-28 10:13:04 +08:00
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 functions are effectively already documented Reviewed-by: Matt Caswell <matt@openssl.org> (Merged from https://github.com/openssl/openssl/pull/14728)
2021-03-29 20:18:10 +08:00
OPENSSL_sk_find(), OPENSSL_sk_find_ex(), OPENSSL_sk_find_all(),
OPENSSL_sk_free(), OPENSSL_sk_insert(), OPENSSL_sk_is_sorted(),
OPENSSL_sk_new(), OPENSSL_sk_new_null(), OPENSSL_sk_new_reserve(),
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().
Use safestack.h exclusively internally. Remove all stack headers from some includes that don't use them. Avoid a genearic untyped stack use. Update stack POD file to include the OPENSSL_sk_ API functions in the notes section. They were mentioned in the name section but not defined anywhere. Reviewed-by: Richard Levitte <levitte@openssl.org> (Merged from https://github.com/openssl/openssl/pull/4430)
2017-09-28 10:13:04 +08:00
Rename lh_xxx,sk_xxx tp OPENSSL_{LH,SK}_xxx Rename sk_xxx to OPENSSL_sk_xxx and _STACK to OPENSSL_STACK Rename lh_xxx API to OPENSSL_LH_xxx and LHASH_NODE to OPENSSL_LH_NODE Make lhash stuff opaque. Use typedefs for function pointers; makes the code simpler. Remove CHECKED_xxx macros. Add documentation; remove old X509-oriented doc. Add API-compat names for entire old API Reviewed-by: Dr. Stephen Henson <steve@openssl.org>
2016-05-20 22:46:29 +08:00
=head1 RETURN VALUES
Make manuals with TYPE conform with man-pages(7) Details from man-pages(7) that are used: Formatting conventions for manual pages describing functions ... Variable names should, like argument names, be specified in italics. ... Formatting conventions (general) ... Special macros, which are usually in uppercase, are in bold. Exception: don't boldface NULL. ... Furthermore, for TYPE used as a placeholder for types and correponding part of function names, we extrapolate that it's both a type and a variable, and should therefore be bold (typical for types and function names) and italic (typical for variables). POD processors don'e know this, so we have to help them along. Therefore: SPARSE_ARRAY_OF(TYPE) => B<SPARSE_ARRAY_OF>(B<I<TYPE>>) ossl_sa_TYPE_num() => B<ossl_sa_I<TYPE>_num>() TYPE => B<I<TYPE>> There are some other less typical uses where one simply has to give formatting some extra though. Reviewed-by: Matt Caswell <matt@openssl.org> (Merged from https://github.com/openssl/openssl/pull/10041)
2019-09-28 13:33:38 +08:00
B<sk_I<TYPE>_num>() returns the number of elements in the stack or B<-1> if the
passed stack is NULL.
Rename lh_xxx,sk_xxx tp OPENSSL_{LH,SK}_xxx Rename sk_xxx to OPENSSL_sk_xxx and _STACK to OPENSSL_STACK Rename lh_xxx API to OPENSSL_LH_xxx and LHASH_NODE to OPENSSL_LH_NODE Make lhash stuff opaque. Use typedefs for function pointers; makes the code simpler. Remove CHECKED_xxx macros. Add documentation; remove old X509-oriented doc. Add API-compat names for entire old API Reviewed-by: Dr. Stephen Henson <steve@openssl.org>
2016-05-20 22:46:29 +08:00
Make manuals with TYPE conform with man-pages(7) Details from man-pages(7) that are used: Formatting conventions for manual pages describing functions ... Variable names should, like argument names, be specified in italics. ... Formatting conventions (general) ... Special macros, which are usually in uppercase, are in bold. Exception: don't boldface NULL. ... Furthermore, for TYPE used as a placeholder for types and correponding part of function names, we extrapolate that it's both a type and a variable, and should therefore be bold (typical for types and function names) and italic (typical for variables). POD processors don'e know this, so we have to help them along. Therefore: SPARSE_ARRAY_OF(TYPE) => B<SPARSE_ARRAY_OF>(B<I<TYPE>>) ossl_sa_TYPE_num() => B<ossl_sa_I<TYPE>_num>() TYPE => B<I<TYPE>> There are some other less typical uses where one simply has to give formatting some extra though. Reviewed-by: Matt Caswell <matt@openssl.org> (Merged from https://github.com/openssl/openssl/pull/10041)
2019-09-28 13:33:38 +08:00
B<sk_I<TYPE>_value>() returns a pointer to a stack element or NULL if the
Rename lh_xxx,sk_xxx tp OPENSSL_{LH,SK}_xxx Rename sk_xxx to OPENSSL_sk_xxx and _STACK to OPENSSL_STACK Rename lh_xxx API to OPENSSL_LH_xxx and LHASH_NODE to OPENSSL_LH_NODE Make lhash stuff opaque. Use typedefs for function pointers; makes the code simpler. Remove CHECKED_xxx macros. Add documentation; remove old X509-oriented doc. Add API-compat names for entire old API Reviewed-by: Dr. Stephen Henson <steve@openssl.org>
2016-05-20 22:46:29 +08:00
index is out of range.
Make manuals with TYPE conform with man-pages(7) Details from man-pages(7) that are used: Formatting conventions for manual pages describing functions ... Variable names should, like argument names, be specified in italics. ... Formatting conventions (general) ... Special macros, which are usually in uppercase, are in bold. Exception: don't boldface NULL. ... Furthermore, for TYPE used as a placeholder for types and correponding part of function names, we extrapolate that it's both a type and a variable, and should therefore be bold (typical for types and function names) and italic (typical for variables). POD processors don'e know this, so we have to help them along. Therefore: SPARSE_ARRAY_OF(TYPE) => B<SPARSE_ARRAY_OF>(B<I<TYPE>>) ossl_sa_TYPE_num() => B<ossl_sa_I<TYPE>_num>() TYPE => B<I<TYPE>> There are some other less typical uses where one simply has to give formatting some extra though. Reviewed-by: Matt Caswell <matt@openssl.org> (Merged from https://github.com/openssl/openssl/pull/10041)
2019-09-28 13:33:38 +08:00
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.
Rename lh_xxx,sk_xxx tp OPENSSL_{LH,SK}_xxx Rename sk_xxx to OPENSSL_sk_xxx and _STACK to OPENSSL_STACK Rename lh_xxx API to OPENSSL_LH_xxx and LHASH_NODE to OPENSSL_LH_NODE Make lhash stuff opaque. Use typedefs for function pointers; makes the code simpler. Remove CHECKED_xxx macros. Add documentation; remove old X509-oriented doc. Add API-compat names for entire old API Reviewed-by: Dr. Stephen Henson <steve@openssl.org>
2016-05-20 22:46:29 +08:00
Make manuals with TYPE conform with man-pages(7) Details from man-pages(7) that are used: Formatting conventions for manual pages describing functions ... Variable names should, like argument names, be specified in italics. ... Formatting conventions (general) ... Special macros, which are usually in uppercase, are in bold. Exception: don't boldface NULL. ... Furthermore, for TYPE used as a placeholder for types and correponding part of function names, we extrapolate that it's both a type and a variable, and should therefore be bold (typical for types and function names) and italic (typical for variables). POD processors don'e know this, so we have to help them along. Therefore: SPARSE_ARRAY_OF(TYPE) => B<SPARSE_ARRAY_OF>(B<I<TYPE>>) ossl_sa_TYPE_num() => B<ossl_sa_I<TYPE>_num>() TYPE => B<I<TYPE>> There are some other less typical uses where one simply has to give formatting some extra though. Reviewed-by: Matt Caswell <matt@openssl.org> (Merged from https://github.com/openssl/openssl/pull/10041)
2019-09-28 13:33:38 +08:00
B<sk_I<TYPE>_reserve>() returns B<1> on successful allocation of the required
memory or B<0> on error.
Add a reserve call to the stack data structure. This allows the caller to guarantee that there is sufficient space for a number of insertions without reallocation. The expansion ratio when reallocating the array is reduced to 1.5 rather than 2. Change bounds testing to use a single size rather than both INT_MAX and SIZE_MAX. This simplifies some of the tests. Switch the stack pointers to data from char * to void * Reviewed-by: Andy Polyakov <appro@openssl.org> (Merged from https://github.com/openssl/openssl/pull/4386)
2017-08-17 08:10:07 +08:00
Make manuals with TYPE conform with man-pages(7) Details from man-pages(7) that are used: Formatting conventions for manual pages describing functions ... Variable names should, like argument names, be specified in italics. ... Formatting conventions (general) ... Special macros, which are usually in uppercase, are in bold. Exception: don't boldface NULL. ... Furthermore, for TYPE used as a placeholder for types and correponding part of function names, we extrapolate that it's both a type and a variable, and should therefore be bold (typical for types and function names) and italic (typical for variables). POD processors don'e know this, so we have to help them along. Therefore: SPARSE_ARRAY_OF(TYPE) => B<SPARSE_ARRAY_OF>(B<I<TYPE>>) ossl_sa_TYPE_num() => B<ossl_sa_I<TYPE>_num>() TYPE => B<I<TYPE>> There are some other less typical uses where one simply has to give formatting some extra though. Reviewed-by: Matt Caswell <matt@openssl.org> (Merged from https://github.com/openssl/openssl/pull/10041)
2019-09-28 13:33:38 +08:00
B<sk_I<TYPE>_set_cmp_func>() returns the old comparison function or NULL if
Rename lh_xxx,sk_xxx tp OPENSSL_{LH,SK}_xxx Rename sk_xxx to OPENSSL_sk_xxx and _STACK to OPENSSL_STACK Rename lh_xxx API to OPENSSL_LH_xxx and LHASH_NODE to OPENSSL_LH_NODE Make lhash stuff opaque. Use typedefs for function pointers; makes the code simpler. Remove CHECKED_xxx macros. Add documentation; remove old X509-oriented doc. Add API-compat names for entire old API Reviewed-by: Dr. Stephen Henson <steve@openssl.org>
2016-05-20 22:46:29 +08:00
there was no old comparison function.
Make manuals with TYPE conform with man-pages(7) Details from man-pages(7) that are used: Formatting conventions for manual pages describing functions ... Variable names should, like argument names, be specified in italics. ... Formatting conventions (general) ... Special macros, which are usually in uppercase, are in bold. Exception: don't boldface NULL. ... Furthermore, for TYPE used as a placeholder for types and correponding part of function names, we extrapolate that it's both a type and a variable, and should therefore be bold (typical for types and function names) and italic (typical for variables). POD processors don'e know this, so we have to help them along. Therefore: SPARSE_ARRAY_OF(TYPE) => B<SPARSE_ARRAY_OF>(B<I<TYPE>>) ossl_sa_TYPE_num() => B<ossl_sa_I<TYPE>_num>() TYPE => B<I<TYPE>> There are some other less typical uses where one simply has to give formatting some extra though. Reviewed-by: Matt Caswell <matt@openssl.org> (Merged from https://github.com/openssl/openssl/pull/10041)
2019-09-28 13:33:38 +08:00
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.
Rename lh_xxx,sk_xxx tp OPENSSL_{LH,SK}_xxx Rename sk_xxx to OPENSSL_sk_xxx and _STACK to OPENSSL_STACK Rename lh_xxx API to OPENSSL_LH_xxx and LHASH_NODE to OPENSSL_LH_NODE Make lhash stuff opaque. Use typedefs for function pointers; makes the code simpler. Remove CHECKED_xxx macros. Add documentation; remove old X509-oriented doc. Add API-compat names for entire old API Reviewed-by: Dr. Stephen Henson <steve@openssl.org>
2016-05-20 22:46:29 +08:00
Make manuals with TYPE conform with man-pages(7) Details from man-pages(7) that are used: Formatting conventions for manual pages describing functions ... Variable names should, like argument names, be specified in italics. ... Formatting conventions (general) ... Special macros, which are usually in uppercase, are in bold. Exception: don't boldface NULL. ... Furthermore, for TYPE used as a placeholder for types and correponding part of function names, we extrapolate that it's both a type and a variable, and should therefore be bold (typical for types and function names) and italic (typical for variables). POD processors don'e know this, so we have to help them along. Therefore: SPARSE_ARRAY_OF(TYPE) => B<SPARSE_ARRAY_OF>(B<I<TYPE>>) ossl_sa_TYPE_num() => B<ossl_sa_I<TYPE>_num>() TYPE => B<I<TYPE>> There are some other less typical uses where one simply has to give formatting some extra though. Reviewed-by: Matt Caswell <matt@openssl.org> (Merged from https://github.com/openssl/openssl/pull/10041)
2019-09-28 13:33:38 +08:00
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.
Rename lh_xxx,sk_xxx tp OPENSSL_{LH,SK}_xxx Rename sk_xxx to OPENSSL_sk_xxx and _STACK to OPENSSL_STACK Rename lh_xxx API to OPENSSL_LH_xxx and LHASH_NODE to OPENSSL_LH_NODE Make lhash stuff opaque. Use typedefs for function pointers; makes the code simpler. Remove CHECKED_xxx macros. Add documentation; remove old X509-oriented doc. Add API-compat names for entire old API Reviewed-by: Dr. Stephen Henson <steve@openssl.org>
2016-05-20 22:46:29 +08:00
Make manuals with TYPE conform with man-pages(7) Details from man-pages(7) that are used: Formatting conventions for manual pages describing functions ... Variable names should, like argument names, be specified in italics. ... Formatting conventions (general) ... Special macros, which are usually in uppercase, are in bold. Exception: don't boldface NULL. ... Furthermore, for TYPE used as a placeholder for types and correponding part of function names, we extrapolate that it's both a type and a variable, and should therefore be bold (typical for types and function names) and italic (typical for variables). POD processors don'e know this, so we have to help them along. Therefore: SPARSE_ARRAY_OF(TYPE) => B<SPARSE_ARRAY_OF>(B<I<TYPE>>) ossl_sa_TYPE_num() => B<ossl_sa_I<TYPE>_num>() TYPE => B<I<TYPE>> There are some other less typical uses where one simply has to give formatting some extra though. Reviewed-by: Matt Caswell <matt@openssl.org> (Merged from https://github.com/openssl/openssl/pull/10041)
2019-09-28 13:33:38 +08:00
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.
Rename lh_xxx,sk_xxx tp OPENSSL_{LH,SK}_xxx Rename sk_xxx to OPENSSL_sk_xxx and _STACK to OPENSSL_STACK Rename lh_xxx API to OPENSSL_LH_xxx and LHASH_NODE to OPENSSL_LH_NODE Make lhash stuff opaque. Use typedefs for function pointers; makes the code simpler. Remove CHECKED_xxx macros. Add documentation; remove old X509-oriented doc. Add API-compat names for entire old API Reviewed-by: Dr. Stephen Henson <steve@openssl.org>
2016-05-20 22:46:29 +08:00
Make manuals with TYPE conform with man-pages(7) Details from man-pages(7) that are used: Formatting conventions for manual pages describing functions ... Variable names should, like argument names, be specified in italics. ... Formatting conventions (general) ... Special macros, which are usually in uppercase, are in bold. Exception: don't boldface NULL. ... Furthermore, for TYPE used as a placeholder for types and correponding part of function names, we extrapolate that it's both a type and a variable, and should therefore be bold (typical for types and function names) and italic (typical for variables). POD processors don'e know this, so we have to help them along. Therefore: SPARSE_ARRAY_OF(TYPE) => B<SPARSE_ARRAY_OF>(B<I<TYPE>>) ossl_sa_TYPE_num() => B<ossl_sa_I<TYPE>_num>() TYPE => B<I<TYPE>> There are some other less typical uses where one simply has to give formatting some extra though. Reviewed-by: Matt Caswell <matt@openssl.org> (Merged from https://github.com/openssl/openssl/pull/10041)
2019-09-28 13:33:38 +08:00
B<sk_I<TYPE>_set>() returns a pointer to the replacement element or NULL on
Rename lh_xxx,sk_xxx tp OPENSSL_{LH,SK}_xxx Rename sk_xxx to OPENSSL_sk_xxx and _STACK to OPENSSL_STACK Rename lh_xxx API to OPENSSL_LH_xxx and LHASH_NODE to OPENSSL_LH_NODE Make lhash stuff opaque. Use typedefs for function pointers; makes the code simpler. Remove CHECKED_xxx macros. Add documentation; remove old X509-oriented doc. Add API-compat names for entire old API Reviewed-by: Dr. Stephen Henson <steve@openssl.org>
2016-05-20 22:46:29 +08:00
error.
Make manuals with TYPE conform with man-pages(7) Details from man-pages(7) that are used: Formatting conventions for manual pages describing functions ... Variable names should, like argument names, be specified in italics. ... Formatting conventions (general) ... Special macros, which are usually in uppercase, are in bold. Exception: don't boldface NULL. ... Furthermore, for TYPE used as a placeholder for types and correponding part of function names, we extrapolate that it's both a type and a variable, and should therefore be bold (typical for types and function names) and italic (typical for variables). POD processors don'e know this, so we have to help them along. Therefore: SPARSE_ARRAY_OF(TYPE) => B<SPARSE_ARRAY_OF>(B<I<TYPE>>) ossl_sa_TYPE_num() => B<ossl_sa_I<TYPE>_num>() TYPE => B<I<TYPE>> There are some other less typical uses where one simply has to give formatting some extra though. Reviewed-by: Matt Caswell <matt@openssl.org> (Merged from https://github.com/openssl/openssl/pull/10041)
2019-09-28 13:33:38 +08:00
B<sk_I<TYPE>_find>() and B<sk_I<TYPE>_find_ex>() return an index to the found
element or B<-1> on error.
Rename lh_xxx,sk_xxx tp OPENSSL_{LH,SK}_xxx Rename sk_xxx to OPENSSL_sk_xxx and _STACK to OPENSSL_STACK Rename lh_xxx API to OPENSSL_LH_xxx and LHASH_NODE to OPENSSL_LH_NODE Make lhash stuff opaque. Use typedefs for function pointers; makes the code simpler. Remove CHECKED_xxx macros. Add documentation; remove old X509-oriented doc. Add API-compat names for entire old API Reviewed-by: Dr. Stephen Henson <steve@openssl.org>
2016-05-20 22:46:29 +08:00
Make manuals with TYPE conform with man-pages(7) Details from man-pages(7) that are used: Formatting conventions for manual pages describing functions ... Variable names should, like argument names, be specified in italics. ... Formatting conventions (general) ... Special macros, which are usually in uppercase, are in bold. Exception: don't boldface NULL. ... Furthermore, for TYPE used as a placeholder for types and correponding part of function names, we extrapolate that it's both a type and a variable, and should therefore be bold (typical for types and function names) and italic (typical for variables). POD processors don'e know this, so we have to help them along. Therefore: SPARSE_ARRAY_OF(TYPE) => B<SPARSE_ARRAY_OF>(B<I<TYPE>>) ossl_sa_TYPE_num() => B<ossl_sa_I<TYPE>_num>() TYPE => B<I<TYPE>> There are some other less typical uses where one simply has to give formatting some extra though. Reviewed-by: Matt Caswell <matt@openssl.org> (Merged from https://github.com/openssl/openssl/pull/10041)
2019-09-28 13:33:38 +08:00
B<sk_I<TYPE>_is_sorted>() returns B<1> if the stack is sorted and B<0> if it is
Rename lh_xxx,sk_xxx tp OPENSSL_{LH,SK}_xxx Rename sk_xxx to OPENSSL_sk_xxx and _STACK to OPENSSL_STACK Rename lh_xxx API to OPENSSL_LH_xxx and LHASH_NODE to OPENSSL_LH_NODE Make lhash stuff opaque. Use typedefs for function pointers; makes the code simpler. Remove CHECKED_xxx macros. Add documentation; remove old X509-oriented doc. Add API-compat names for entire old API Reviewed-by: Dr. Stephen Henson <steve@openssl.org>
2016-05-20 22:46:29 +08:00
not.
Make manuals with TYPE conform with man-pages(7) Details from man-pages(7) that are used: Formatting conventions for manual pages describing functions ... Variable names should, like argument names, be specified in italics. ... Formatting conventions (general) ... Special macros, which are usually in uppercase, are in bold. Exception: don't boldface NULL. ... Furthermore, for TYPE used as a placeholder for types and correponding part of function names, we extrapolate that it's both a type and a variable, and should therefore be bold (typical for types and function names) and italic (typical for variables). POD processors don'e know this, so we have to help them along. Therefore: SPARSE_ARRAY_OF(TYPE) => B<SPARSE_ARRAY_OF>(B<I<TYPE>>) ossl_sa_TYPE_num() => B<ossl_sa_I<TYPE>_num>() TYPE => B<I<TYPE>> There are some other less typical uses where one simply has to give formatting some extra though. Reviewed-by: Matt Caswell <matt@openssl.org> (Merged from https://github.com/openssl/openssl/pull/10041)
2019-09-28 13:33:38 +08:00
B<sk_I<TYPE>_dup>() and B<sk_I<TYPE>_deep_copy>() return a pointer to the copy
Allow NULL arg to OPENSSL_sk_{dup,deep_copy} returning empty stack This simplifies many usages Reviewed-by: Tomas Mraz <tomas@openssl.org> (Merged from https://github.com/openssl/openssl/pull/14040)
2020-12-24 02:33:03 +08:00
of the stack or NULL on error.
Rename lh_xxx,sk_xxx tp OPENSSL_{LH,SK}_xxx Rename sk_xxx to OPENSSL_sk_xxx and _STACK to OPENSSL_STACK Rename lh_xxx API to OPENSSL_LH_xxx and LHASH_NODE to OPENSSL_LH_NODE Make lhash stuff opaque. Use typedefs for function pointers; makes the code simpler. Remove CHECKED_xxx macros. Add documentation; remove old X509-oriented doc. Add API-compat names for entire old API Reviewed-by: Dr. Stephen Henson <steve@openssl.org>
2016-05-20 22:46:29 +08:00
=head1 HISTORY
Before OpenSSL 1.1.0, this was implemented via macros and not inline functions
and was not a public API.
Make manuals with TYPE conform with man-pages(7) Details from man-pages(7) that are used: Formatting conventions for manual pages describing functions ... Variable names should, like argument names, be specified in italics. ... Formatting conventions (general) ... Special macros, which are usually in uppercase, are in bold. Exception: don't boldface NULL. ... Furthermore, for TYPE used as a placeholder for types and correponding part of function names, we extrapolate that it's both a type and a variable, and should therefore be bold (typical for types and function names) and italic (typical for variables). POD processors don'e know this, so we have to help them along. Therefore: SPARSE_ARRAY_OF(TYPE) => B<SPARSE_ARRAY_OF>(B<I<TYPE>>) ossl_sa_TYPE_num() => B<ossl_sa_I<TYPE>_num>() TYPE => B<I<TYPE>> There are some other less typical uses where one simply has to give formatting some extra though. Reviewed-by: Matt Caswell <matt@openssl.org> (Merged from https://github.com/openssl/openssl/pull/10041)
2019-09-28 13:33:38 +08:00
B<sk_I<TYPE>_reserve>() and B<sk_I<TYPE>_new_reserve>() were added in OpenSSL
1.1.1.
Add sk_TYPE_new_reserve() function This is a combination of sk_new and sk_reserve, to make it more convenient to allocate a new stack with reserved memory and comaprison function (if any). Reviewed-by: Paul Dale <paul.dale@oracle.com> Reviewed-by: Andy Polyakov <appro@openssl.org> Reviewed-by: Richard Levitte <levitte@openssl.org> (Merged from https://github.com/openssl/openssl/pull/4559)
2017-10-20 01:42:39 +08:00
doc: note that the stack find functions no longer modify the stack Reviewed-by: Tomas Mraz <tomas@openssl.org> Reviewed-by: Todd Short <todd.short@me.com> (Merged from https://github.com/openssl/openssl/pull/20842)
2023-04-27 09:12:51 +08:00
From OpenSSL 3.2.0, the B<sk_I<TYPE>_find>(), B<sk_I<TYPE>_find_ex>()
and B<sk_I<TYPE>_find_all>() calls are read-only and do not sort the
stack. To avoid any performance implications this change introduces,
B<sk_I<TYPE>_sort>() should be called before these find operations.
Make OPENSSL_sk_push return only 0 or 1 Most of the callers do not actually check for the special -1 return condition because they do not pass NULL to it. It is also extremely improbable that any code depends on this -1 return value in this condition so it can be safely changed to 0 return. Reviewed-by: Matt Caswell <matt@openssl.org> Reviewed-by: Ben Kaduk <kaduk@mit.edu> (Merged from https://github.com/openssl/openssl/pull/22930)
2023-12-04 18:16:45 +08:00
Before OpenSSL 3.3.0 B<sk_I<TYPE>_push>() returned -1 if I<sk> was NULL. It
was changed to return 0 in this condition as for other errors.
Rename lh_xxx,sk_xxx tp OPENSSL_{LH,SK}_xxx Rename sk_xxx to OPENSSL_sk_xxx and _STACK to OPENSSL_STACK Rename lh_xxx API to OPENSSL_LH_xxx and LHASH_NODE to OPENSSL_LH_NODE Make lhash stuff opaque. Use typedefs for function pointers; makes the code simpler. Remove CHECKED_xxx macros. Add documentation; remove old X509-oriented doc. Add API-compat names for entire old API Reviewed-by: Dr. Stephen Henson <steve@openssl.org>
2016-05-20 22:46:29 +08:00
=head1 COPYRIGHT
Copyright year updates Reviewed-by: Neil Horman <nhorman@openssl.org> Release: yes (cherry picked from commit 0ce7d1f355c1240653e320a3f6f8109c1f05f8c0) Reviewed-by: Hugo Landau <hlandau@openssl.org> Reviewed-by: Tomas Mraz <tomas@openssl.org> (Merged from https://github.com/openssl/openssl/pull/24034)
2024-03-20 20:07:54 +08:00
Copyright 2000-2024 The OpenSSL Project Authors. All Rights Reserved.
Rename lh_xxx,sk_xxx tp OPENSSL_{LH,SK}_xxx Rename sk_xxx to OPENSSL_sk_xxx and _STACK to OPENSSL_STACK Rename lh_xxx API to OPENSSL_LH_xxx and LHASH_NODE to OPENSSL_LH_NODE Make lhash stuff opaque. Use typedefs for function pointers; makes the code simpler. Remove CHECKED_xxx macros. Add documentation; remove old X509-oriented doc. Add API-compat names for entire old API Reviewed-by: Dr. Stephen Henson <steve@openssl.org>
2016-05-20 22:46:29 +08:00
Following the license change, modify the boilerplates in doc/man3/ [skip ci] Reviewed-by: Matt Caswell <matt@openssl.org> (Merged from https://github.com/openssl/openssl/pull/7829)
2018-12-06 21:04:44 +08:00
Licensed under the Apache License 2.0 (the "License"). You may not use
Rename lh_xxx,sk_xxx tp OPENSSL_{LH,SK}_xxx Rename sk_xxx to OPENSSL_sk_xxx and _STACK to OPENSSL_STACK Rename lh_xxx API to OPENSSL_LH_xxx and LHASH_NODE to OPENSSL_LH_NODE Make lhash stuff opaque. Use typedefs for function pointers; makes the code simpler. Remove CHECKED_xxx macros. Add documentation; remove old X509-oriented doc. Add API-compat names for entire old API Reviewed-by: Dr. Stephen Henson <steve@openssl.org>
2016-05-20 22:46:29 +08:00
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut