VirtualBox

忽略:
時間撮記:
2022-3-3 下午07:17:34 (3 年 以前)
作者:
vboxsync
svn:sync-xref-src-repo-rev:
150325
訊息:

libs/openssl-3.0.1: started applying and adjusting our OpenSSL changes to 3.0.1. bugref:10128

位置:
trunk/src/libs/openssl-3.0.1
檔案:
修改 2 筆資料

圖例:

未更動
新增
刪除

  • trunk/src/libs/openssl-3.0.1

    • 屬性 svn:mergeinfo

      •  

        old new  
        1212/vendor/openssl/1.1.1c:131722-131725
        1313/vendor/openssl/1.1.1k:145841-145843
         14/vendor/openssl/3.0.1:150323-150324
         15/vendor/openssl/current:147554-150322

  • trunk/src/libs/openssl-3.0.1/doc/man3/DEFINE_STACK_OF.pod

    r91772 r94082  
    99sk_TYPE_delete_ptr, sk_TYPE_push, sk_TYPE_unshift, sk_TYPE_pop,
    1010sk_TYPE_shift, sk_TYPE_pop_free, sk_TYPE_insert, sk_TYPE_set,
    11 sk_TYPE_find, sk_TYPE_find_ex, sk_TYPE_sort, sk_TYPE_is_sorted,
    12 sk_TYPE_dup, sk_TYPE_deep_copy, sk_TYPE_set_cmp_func, sk_TYPE_new_reserve
     11sk_TYPE_find, sk_TYPE_find_ex, sk_TYPE_find_all, sk_TYPE_sort,
     12sk_TYPE_is_sorted, sk_TYPE_dup, sk_TYPE_deep_copy, sk_TYPE_set_cmp_func,
     13sk_TYPE_new_reserve,
     14OPENSSL_sk_deep_copy, OPENSSL_sk_delete, OPENSSL_sk_delete_ptr,
     15OPENSSL_sk_dup, OPENSSL_sk_find, OPENSSL_sk_find_ex, OPENSSL_sk_find_all,
     16OPENSSL_sk_free, OPENSSL_sk_insert, OPENSSL_sk_is_sorted, OPENSSL_sk_new,
     17OPENSSL_sk_new_null, OPENSSL_sk_new_reserve, OPENSSL_sk_num, OPENSSL_sk_pop,
     18OPENSSL_sk_pop_free, OPENSSL_sk_push, OPENSSL_sk_reserve, OPENSSL_sk_set,
     19OPENSSL_sk_set_cmp_func, OPENSSL_sk_shift, OPENSSL_sk_sort,
     20OPENSSL_sk_unshift, OPENSSL_sk_value, OPENSSL_sk_zero
    1321- stack container
    1422
    1523=head1 SYNOPSIS
    1624
    17 =for comment generic
     25=for openssl generic
    1826
    1927 #include <openssl/safestack.h>
    … …  
    4755 int sk_TYPE_find(STACK_OF(TYPE) *sk, TYPE *ptr);
    4856 int sk_TYPE_find_ex(STACK_OF(TYPE) *sk, TYPE *ptr);
     57 int sk_TYPE_find_all(STACK_OF(TYPE) *sk, TYPE *ptr, int *pnum);
    4958 void sk_TYPE_sort(const STACK_OF(TYPE) *sk);
    5059 int sk_TYPE_is_sorted(const STACK_OF(TYPE) *sk);
    … …  
    6271described below in a header file. These macros define typesafe inline
    6372functions that wrap around the utility B<OPENSSL_sk_> API.
    64 In the description here, I<TYPE> is used
    65 as a placeholder for any of the OpenSSL datatypes, such as I<X509>.
    66 
    67 STACK_OF() returns the name for a stack of the specified B<TYPE>.
    68 DEFINE_STACK_OF() creates set of functions for a stack of B<TYPE>. This
    69 will mean that type B<TYPE> is stored in each stack, the type is referenced by
    70 STACK_OF(TYPE) and each function name begins with I<sk_TYPE_>. For example:
    71 
     73In the description here, B<I<TYPE>> is used
     74as a placeholder for any of the OpenSSL datatypes, such as B<X509>.
     75
     76The STACK_OF() macro returns the name for a stack of the specified B<I<TYPE>>.
     77This is an opaque pointer to a structure declaration.
     78This can be used in every header file that references the stack.
     79There are several B<DEFINE...> macros that create static inline functions
     80for all of the functions described on this page.
     81This should normally be used in one source file, and the stack manipulation
     82is wrapped with application-specific functions.
     83
     84DEFINE_STACK_OF() creates set of functions for a stack of B<I<TYPE>> elements.
     85The type is referenced by
     86B<STACK_OF>(B<I<TYPE>>) and each function name begins with B<sk_I<TYPE>_>.
     87DEFINE_STACK_OF_CONST() is identical to DEFINE_STACK_OF() except
     88each element is constant.
     89
     90 /* DEFINE_STACK_OF(TYPE) */
    7291 TYPE *sk_TYPE_value(STACK_OF(TYPE) *sk, int idx);
    73 
    74 DEFINE_STACK_OF_CONST() is identical to DEFINE_STACK_OF() except
    75 each element is constant. For example:
    76 
     92 /* DEFINE_STACK_OF_CONST(TYPE) */
    7793 const TYPE *sk_TYPE_value(STACK_OF(TYPE) *sk, int idx);
    7894
    79 DEFINE_SPECIAL_STACK_OF() defines a stack of B<TYPE> but
    80 each function uses B<FUNCNAME> in the function name. For example:
    81 
     95DEFINE_SPECIAL_STACK_OF() and DEFINE_SPECIAL_STACK_OF_CONST() are similar
     96except B<FUNCNAME> is used in the function names:
     97
     98 /* DEFINE_SPECIAL_STACK_OF(TYPE, FUNCNAME) */
    8299 TYPE *sk_FUNCNAME_value(STACK_OF(TYPE) *sk, int idx);
    83 
    84 DEFINE_SPECIAL_STACK_OF_CONST() is similar except that each element is
    85 constant:
    86 
     100 /* DEFINE_SPECIAL_STACK_OF(TYPE, FUNCNAME) */
    87101 const TYPE *sk_FUNCNAME_value(STACK_OF(TYPE) *sk, int idx);
    88102
    89 sk_TYPE_num() returns the number of elements in B<sk> or -1 if B<sk> is
    90 B<NULL>.
    91 
    92 sk_TYPE_value() returns element B<idx> in B<sk>, where B<idx> starts at
    93 zero. If B<idx> is out of range then B<NULL> is returned.
    94 
    95 sk_TYPE_new() allocates a new empty stack using comparison function B<compare>.
    96 If B<compare> is B<NULL> then no comparison function is used. This function is
    97 equivalent to sk_TYPE_new_reserve(compare, 0).
    98 
    99 sk_TYPE_new_null() allocates a new empty stack with no comparison function. This
    100 function is equivalent to sk_TYPE_new_reserve(NULL, 0).
    101 
    102 sk_TYPE_reserve() allocates additional memory in the B<sk> structure
    103 such that the next B<n> calls to sk_TYPE_insert(), sk_TYPE_push()
    104 or sk_TYPE_unshift() will not fail or cause memory to be allocated
    105 or reallocated. If B<n> is zero, any excess space allocated in the
    106 B<sk> structure is freed. On error B<sk> is unchanged.
    107 
    108 sk_TYPE_new_reserve() allocates a new stack. The new stack will have additional
    109 memory allocated to hold B<n> elements if B<n> is positive. The next B<n> calls
    110 to sk_TYPE_insert(), sk_TYPE_push() or sk_TYPE_unshift() will not fail or cause
    111 memory to be allocated or reallocated. If B<n> is zero or less than zero, no
    112 memory is allocated. sk_TYPE_new_reserve() also sets the comparison function
    113 B<compare> to the newly created stack. If B<compare> is B<NULL> then no
    114 comparison function is used.
    115 
    116 sk_TYPE_set_cmp_func() sets the comparison function of B<sk> to B<compare>.
    117 The previous comparison function is returned or B<NULL> if there was
    118 no previous comparison function.
    119 
    120 sk_TYPE_free() frees up the B<sk> structure. It does B<not> free up any
    121 elements of B<sk>. After this call B<sk> is no longer valid.
    122 
    123 sk_TYPE_zero() sets the number of elements in B<sk> to zero. It does not free
    124 B<sk> so after this call B<sk> is still valid.
    125 
    126 sk_TYPE_pop_free() frees up all elements of B<sk> and B<sk> itself. The
     103B<sk_I<TYPE>_num>() returns the number of elements in I<sk> or -1 if I<sk> is
     104NULL.
     105
     106B<sk_I<TYPE>_value>() returns element I<idx> in I<sk>, where I<idx> starts at
     107zero. If I<idx> is out of range then NULL is returned.
     108
     109B<sk_I<TYPE>_new>() allocates a new empty stack using comparison function
     110I<compare>. If I<compare> is NULL then no comparison function is used. This
     111function is equivalent to B<sk_I<TYPE>_new_reserve>(I<compare>, 0).
     112
     113B<sk_I<TYPE>_new_null>() allocates a new empty stack with no comparison
     114function. This function is equivalent to B<sk_I<TYPE>_new_reserve>(NULL, 0).
     115
     116B<sk_I<TYPE>_reserve>() allocates additional memory in the I<sk> structure
     117such that the next I<n> calls to B<sk_I<TYPE>_insert>(), B<sk_I<TYPE>_push>()
     118or B<sk_I<TYPE>_unshift>() will not fail or cause memory to be allocated
     119or reallocated. If I<n> is zero, any excess space allocated in the
     120I<sk> structure is freed. On error I<sk> is unchanged.
     121
     122B<sk_I<TYPE>_new_reserve>() allocates a new stack. The new stack will have
     123additional memory allocated to hold I<n> elements if I<n> is positive.
     124The next I<n> calls to B<sk_I<TYPE>_insert>(), B<sk_I<TYPE>_push>() or
     125B<sk_I<TYPE>_unshift>() will not fail or cause memory to be allocated or
     126reallocated. If I<n> is zero or less than zero, no memory is allocated.
     127B<sk_I<TYPE>_new_reserve>() also sets the comparison function I<compare>
     128to the newly created stack. If I<compare> is NULL then no comparison
     129function is used.
     130
     131B<sk_I<TYPE>_set_cmp_func>() sets the comparison function of I<sk> to
     132I<compare>. The previous comparison function is returned or NULL if there
     133was no previous comparison function.
     134
     135B<sk_I<TYPE>_free>() frees up the I<sk> structure. It does I<not> free up any
     136elements of I<sk>. After this call I<sk> is no longer valid.
     137
     138B<sk_I<TYPE>_zero>() sets the number of elements in I<sk> to zero. It does not
     139free I<sk> so after this call I<sk> is still valid.
     140
     141B<sk_I<TYPE>_pop_free>() frees up all elements of I<sk> and I<sk> itself. The
    127142free function freefunc() is called on each element to free it.
    128143
    129 sk_TYPE_delete() deletes element B<i> from B<sk>. It returns the deleted
    130 element or B<NULL> if B<i> is out of range.
    131 
    132 sk_TYPE_delete_ptr() deletes element matching B<ptr> from B<sk>. It returns
    133 the deleted element or B<NULL> if no element matching B<ptr> was found.
    134 
    135 sk_TYPE_insert() inserts B<ptr> into B<sk> at position B<idx>. Any existing
    136 elements at or after B<idx> are moved downwards. If B<idx> is out of range
    137 the new element is appended to B<sk>. sk_TYPE_insert() either returns the
    138 number of elements in B<sk> after the new element is inserted or zero if
    139 an error (such as memory allocation failure) occurred.
    140 
    141 sk_TYPE_push() appends B<ptr> to B<sk> it is equivalent to:
     144B<sk_I<TYPE>_delete>() deletes element I<i> from I<sk>. It returns the deleted
     145element or NULL if I<i> is out of range.
     146
     147B<sk_I<TYPE>_delete_ptr>() deletes element matching I<ptr> from I<sk>. It
     148returns the deleted element or NULL if no element matching I<ptr> was found.
     149
     150B<sk_I<TYPE>_insert>() inserts I<ptr> into I<sk> at position I<idx>. Any
     151existing elements at or after I<idx> are moved downwards. If I<idx> is out
     152of range the new element is appended to I<sk>. B<sk_I<TYPE>_insert>() either
     153returns the number of elements in I<sk> after the new element is inserted or
     154zero if an error (such as memory allocation failure) occurred.
     155
     156B<sk_I<TYPE>_push>() appends I<ptr> to I<sk> it is equivalent to:
    142157
    143158 sk_TYPE_insert(sk, ptr, -1);
    144159
    145 sk_TYPE_unshift() inserts B<ptr> at the start of B<sk> it is equivalent to:
     160B<sk_I<TYPE>_unshift>() inserts I<ptr> at the start of I<sk> it is equivalent
     161to:
    146162
    147163 sk_TYPE_insert(sk, ptr, 0);
    148164
    149 sk_TYPE_pop() returns and removes the last element from B<sk>.
    150 
    151 sk_TYPE_shift() returns and removes the first element from B<sk>.
    152 
    153 sk_TYPE_set() sets element B<idx> of B<sk> to B<ptr> replacing the current
    154 element. The new element value is returned or B<NULL> if an error occurred:
    155 this will only happen if B<sk> is B<NULL> or B<idx> is out of range.
    156 
    157 sk_TYPE_find() searches B<sk> for the element B<ptr>.  In the case
     165B<sk_I<TYPE>_pop>() returns and removes the last element from I<sk>.
     166
     167B<sk_I<TYPE>_shift>() returns and removes the first element from I<sk>.
     168
     169B<sk_I<TYPE>_set>() sets element I<idx> of I<sk> to I<ptr> replacing the current
     170element. The new element value is returned or NULL if an error occurred:
     171this will only happen if I<sk> is NULL or I<idx> is out of range.
     172
     173B<sk_I<TYPE>_find>() searches I<sk> for the element I<ptr>.  In the case
    158174where no comparison function has been specified, the function performs
    159 a linear search for a pointer equal to B<ptr>. The index of the first
     175a linear search for a pointer equal to I<ptr>. The index of the first
    160176matching element is returned or B<-1> if there is no match. In the case
    161 where a comparison function has been specified, B<sk> is sorted then
    162 sk_TYPE_find() returns the index of a matching element or B<-1> if there
    163 is no match. Note that, in this case, the matching element returned is
    164 not guaranteed to be the first; the comparison function will usually
     177where a comparison function has been specified, I<sk> is sorted and
     178B<sk_I<TYPE>_find>() returns the index of a matching element or B<-1> if there
     179is no match. Note that, in this case the comparison function will usually
    165180compare the values pointed to rather than the pointers themselves and
    166 the order of elements in B<sk> could change.
    167 
    168 sk_TYPE_find_ex() operates like sk_TYPE_find() except when a comparison
    169 function has been specified and no matching element is found. Instead
    170 of returning B<-1>, sk_TYPE_find_ex() returns the index of the element
    171 either before or after the location where B<ptr> would be if it were
    172 present in B<sk>.
    173 
    174 sk_TYPE_sort() sorts B<sk> using the supplied comparison function.
    175 
    176 sk_TYPE_is_sorted() returns B<1> if B<sk> is sorted and B<0> otherwise.
    177 
    178 sk_TYPE_dup() returns a copy of B<sk>. Note the pointers in the copy
    179 are identical to the original.
    180 
    181 sk_TYPE_deep_copy() returns a new stack where each element has been copied.
    182 Copying is performed by the supplied copyfunc() and freeing by freefunc(). The
    183 function freefunc() is only called if an error occurs.
     181the order of elements in I<sk> can change. Note that because the stack may be
     182sorted as the result of a B<sk_I<TYPE>_find>() call, if a lock is being used to
     183synchronise access to the stack across multiple threads, then that lock must be
     184a "write" lock.
     185
     186B<sk_I<TYPE>_find_ex>() operates like B<sk_I<TYPE>_find>() except when a
     187comparison function has been specified and no matching element is found.
     188Instead of returning B<-1>, B<sk_I<TYPE>_find_ex>() returns the index of the
     189element either before or after the location where I<ptr> would be if it were
     190present in I<sk>. The function also does not guarantee that the first matching
     191element in the sorted stack is returned.
     192
     193B<sk_I<TYPE>_find_all>() operates like B<sk_I<TYPE>_find>() but it also
     194sets the I<*pnum> to number of matching elements in the stack. In case
     195no comparison function has been specified the I<*pnum> will be always set
     196to 1 if matching element was found, 0 otherwise.
     197
     198B<sk_I<TYPE>_sort>() sorts I<sk> using the supplied comparison function.
     199
     200B<sk_I<TYPE>_is_sorted>() returns B<1> if I<sk> is sorted and B<0> otherwise.
     201
     202B<sk_I<TYPE>_dup>() returns a shallow copy of I<sk>
     203or an empty stack if the passed stack is NULL.
     204Note the pointers in the copy are identical to the original.
     205
     206B<sk_I<TYPE>_deep_copy>() returns a new stack where each element has been
     207copied or an empty stack if the passed stack is NULL.
     208Copying is performed by the supplied copyfunc() and freeing by freefunc().
     209The function freefunc() is only called if an error occurs.
    184210
    185211=head1 NOTES
    186212
    187213Care should be taken when accessing stacks in multi-threaded environments.
    188 Any operation which increases the size of a stack such as sk_TYPE_insert() or
    189 sk_push() can "grow" the size of an internal array and cause race conditions
    190 if the same stack is accessed in a different thread. Operations such as
    191 sk_find() and sk_sort() can also reorder the stack.
     214Any operation which increases the size of a stack such as B<sk_I<TYPE>_insert>()
     215or B<sk_I<TYPE>_push>() can "grow" the size of an internal array and cause race
     216conditions if the same stack is accessed in a different thread. Operations such
     217as B<sk_I<TYPE>_find>() and B<sk_I<TYPE>_sort>() can also reorder the stack.
    192218
    193219Any comparison function supplied should use a metric suitable
    194220for use in a binary search operation. That is it should return zero, a
    195 positive or negative value if B<a> is equal to, greater than
    196 or less than B<b> respectively.
     221positive or negative value if I<a> is equal to, greater than
     222or less than I<b> respectively.
    197223
    198224Care should be taken when checking the return values of the functions
    199 sk_TYPE_find() and sk_TYPE_find_ex(). They return an index to the
     225B<sk_I<TYPE>_find>() and B<sk_I<TYPE>_find_ex>(). They return an index to the
    200226matching element. In particular B<0> indicates a matching first element.
    201227A failed search is indicated by a B<-1> return value.
    … …  
    207233It defines these functions: OPENSSL_sk_deep_copy(),
    208234OPENSSL_sk_delete(), OPENSSL_sk_delete_ptr(), OPENSSL_sk_dup(),
    209 OPENSSL_sk_find(), OPENSSL_sk_find_ex(), OPENSSL_sk_free(),
    210 OPENSSL_sk_insert(), OPENSSL_sk_is_sorted(), OPENSSL_sk_new(),
    211 OPENSSL_sk_new_null(), OPENSSL_sk_num(), OPENSSL_sk_pop(),
    212 OPENSSL_sk_pop_free(), OPENSSL_sk_push(), OPENSSL_sk_reserve(),
    213 OPENSSL_sk_set(), OPENSSL_sk_set_cmp_func(), OPENSSL_sk_shift(),
    214 OPENSSL_sk_sort(), OPENSSL_sk_unshift(), OPENSSL_sk_value(),
    215 OPENSSL_sk_zero().
     235OPENSSL_sk_find(), OPENSSL_sk_find_ex(), OPENSSL_sk_find_all(),
     236OPENSSL_sk_free(), OPENSSL_sk_insert(), OPENSSL_sk_is_sorted(),
     237OPENSSL_sk_new(), OPENSSL_sk_new_null(), OPENSSL_sk_new_reserve(),
     238OPENSSL_sk_num(), OPENSSL_sk_pop(), OPENSSL_sk_pop_free(), OPENSSL_sk_push(),
     239OPENSSL_sk_reserve(), OPENSSL_sk_set(), OPENSSL_sk_set_cmp_func(),
     240OPENSSL_sk_shift(), OPENSSL_sk_sort(), OPENSSL_sk_unshift(),
     241OPENSSL_sk_value(), OPENSSL_sk_zero().
    216242
    217243=head1 RETURN VALUES
    218244
    219 sk_TYPE_num() returns the number of elements in the stack or B<-1> if the
    220 passed stack is B<NULL>.
    221 
    222 sk_TYPE_value() returns a pointer to a stack element or B<NULL> if the
     245B<sk_I<TYPE>_num>() returns the number of elements in the stack or B<-1> if the
     246passed stack is NULL.
     247
     248B<sk_I<TYPE>_value>() returns a pointer to a stack element or NULL if the
    223249index is out of range.
    224250
    225 sk_TYPE_new(), sk_TYPE_new_null() and sk_TYPE_new_reserve() return an empty
    226 stack or B<NULL> if an error occurs.
    227 
    228 sk_TYPE_reserve() returns B<1> on successful allocation of the required memory
    229 or B<0> on error.
    230 
    231 sk_TYPE_set_cmp_func() returns the old comparison function or B<NULL> if
     251B<sk_I<TYPE>_new>(), B<sk_I<TYPE>_new_null>() and B<sk_I<TYPE>_new_reserve>()
     252return an empty stack or NULL if an error occurs.
     253
     254B<sk_I<TYPE>_reserve>() returns B<1> on successful allocation of the required
     255memory or B<0> on error.
     256
     257B<sk_I<TYPE>_set_cmp_func>() returns the old comparison function or NULL if
    232258there was no old comparison function.
    233259
    234 sk_TYPE_free(), sk_TYPE_zero(), sk_TYPE_pop_free() and sk_TYPE_sort() do
    235 not return values.
    236 
    237 sk_TYPE_pop(), sk_TYPE_shift(), sk_TYPE_delete() and sk_TYPE_delete_ptr()
    238 return a pointer to the deleted element or B<NULL> on error.
    239 
    240 sk_TYPE_insert(), sk_TYPE_push() and sk_TYPE_unshift() return the total
    241 number of elements in the stack and 0 if an error occurred.
    242 
    243 sk_TYPE_set() returns a pointer to the replacement element or B<NULL> on
     260B<sk_I<TYPE>_free>(), B<sk_I<TYPE>_zero>(), B<sk_I<TYPE>_pop_free>() and
     261B<sk_I<TYPE>_sort>() do not return values.
     262
     263B<sk_I<TYPE>_pop>(), B<sk_I<TYPE>_shift>(), B<sk_I<TYPE>_delete>() and
     264B<sk_I<TYPE>_delete_ptr>() return a pointer to the deleted element or NULL
     265on error.
     266
     267B<sk_I<TYPE>_insert>(), B<sk_I<TYPE>_push>() and B<sk_I<TYPE>_unshift>() return
     268the total number of elements in the stack and 0 if an error occurred.
     269
     270B<sk_I<TYPE>_set>() returns a pointer to the replacement element or NULL on
    244271error.
    245272
    246 sk_TYPE_find() and sk_TYPE_find_ex() return an index to the found element
    247 or B<-1> on error.
    248 
    249 sk_TYPE_is_sorted() returns B<1> if the stack is sorted and B<0> if it is
     273B<sk_I<TYPE>_find>() and B<sk_I<TYPE>_find_ex>() return an index to the found
     274element or B<-1> on error.
     275
     276B<sk_I<TYPE>_is_sorted>() returns B<1> if the stack is sorted and B<0> if it is
    250277not.
    251278
    252 sk_TYPE_dup() and sk_TYPE_deep_copy() return a pointer to the copy of the
    253 stack.
     279B<sk_I<TYPE>_dup>() and B<sk_I<TYPE>_deep_copy>() return a pointer to the copy
     280of the stack or NULL on error.
    254281
    255282=head1 HISTORY
    … …  
    258285and was not a public API.
    259286
    260 sk_TYPE_reserve() and sk_TYPE_new_reserve() were added in OpenSSL 1.1.1.
     287B<sk_I<TYPE>_reserve>() and B<sk_I<TYPE>_new_reserve>() were added in OpenSSL
     2881.1.1.
    261289
    262290=head1 COPYRIGHT
    263291
    264 Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved.
    265 
    266 Licensed under the OpenSSL license (the "License").  You may not use
     292Copyright 2000-2021 The OpenSSL Project Authors. All Rights Reserved.
     293
     294Licensed under the Apache License 2.0 (the "License").  You may not use
    267295this file except in compliance with the License.  You can obtain a copy
    268296in the file LICENSE in the source distribution or at
注意: 瀏覽 TracChangeset 來幫助您使用更動檢視器

© 2025 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette