From eb8dd9dca1228af0cd132f515509051ecfabf6f6 Mon Sep 17 00:00:00 2001 From: cvs2svn Date: Mon, 14 Apr 2025 17:32:06 +0000 Subject: This commit was manufactured by cvs2git to create tag 'tb_20250414'. --- src/lib/libcrypto/man/OPENSSL_sk_new.3 | 553 --------------------------------- 1 file changed, 553 deletions(-) delete mode 100644 src/lib/libcrypto/man/OPENSSL_sk_new.3 (limited to 'src/lib/libcrypto/man/OPENSSL_sk_new.3') diff --git a/src/lib/libcrypto/man/OPENSSL_sk_new.3 b/src/lib/libcrypto/man/OPENSSL_sk_new.3 deleted file mode 100644 index 8f06bb4212..0000000000 --- a/src/lib/libcrypto/man/OPENSSL_sk_new.3 +++ /dev/null @@ -1,553 +0,0 @@ -.\" $OpenBSD: OPENSSL_sk_new.3,v 1.13 2024/03/04 09:47:34 tb Exp $ -.\" -.\" Copyright (c) 2018 Ingo Schwarze -.\" -.\" Permission to use, copy, modify, and distribute this software for any -.\" purpose with or without fee is hereby granted, provided that the above -.\" copyright notice and this permission notice appear in all copies. -.\" -.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES -.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF -.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR -.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES -.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN -.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF -.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. -.\" -.Dd $Mdocdate: March 4 2024 $ -.Dt OPENSSL_SK_NEW 3 -.Os -.Sh NAME -.Nm sk_new_null , -.Nm sk_new , -.Nm sk_set_cmp_func , -.Nm sk_dup , -.Nm sk_free , -.Nm sk_pop_free , -.Nm sk_num , -.Nm sk_value , -.Nm sk_find , -.Nm sk_sort , -.Nm sk_is_sorted , -.Nm sk_push , -.Nm sk_unshift , -.Nm sk_insert , -.Nm sk_set , -.Nm sk_pop , -.Nm sk_shift , -.Nm sk_delete , -.Nm sk_delete_ptr , -.Nm sk_zero -.Nd variable-sized arrays of void pointers, called OpenSSL stacks -.Sh SYNOPSIS -.In openssl/stack.h -.Ft _STACK * -.Fn sk_new_null void -.Ft _STACK * -.Fo sk_new -.Fa "int (*compfunc)(const void *, const void *)" -.Fc -.Ft old_function_pointer -.Fo sk_set_cmp_func -.Fa "_STACK *stack" -.Fa "int (*compfunc)(const void *, const void *)" -.Fc -.Ft _STACK * -.Fo sk_dup -.Fa "_STACK *stack" -.Fc -.Ft void -.Fo sk_free -.Fa "_STACK *stack" -.Fc -.Ft void -.Fo sk_pop_free -.Fa "_STACK *stack" -.Fa "void (*freefunc)(void *)" -.Fc -.Ft int -.Fo sk_num -.Fa "const _STACK *stack" -.Fc -.Ft void * -.Fo sk_value -.Fa "const _STACK *stack" -.Fa "int index" -.Fc -.Ft int -.Fo sk_find -.Fa "_STACK *stack" -.Fa "void *wanted" -.Fc -.Ft void -.Fo sk_sort -.Fa "_STACK *stack" -.Fc -.Ft int -.Fo sk_is_sorted -.Fa "const _STACK *stack" -.Fc -.Ft int -.Fo sk_push -.Fa "_STACK *stack" -.Fa "void *new_item" -.Fc -.Ft int -.Fo sk_unshift -.Fa "_STACK *stack" -.Fa "void *new_item" -.Fc -.Ft int -.Fo sk_insert -.Fa "_STACK *stack" -.Fa "void *new_item" -.Fa "int index" -.Fc -.Ft void * -.Fo sk_set -.Fa "_STACK *stack" -.Fa "int index" -.Fa "void *new_item" -.Fc -.Ft void * -.Fo sk_pop -.Fa "_STACK *stack" -.Fc -.Ft void * -.Fo sk_shift -.Fa "_STACK *stack" -.Fc -.Ft void * -.Fo sk_delete -.Fa "_STACK *stack" -.Fa "int index" -.Fc -.Ft void * -.Fo sk_delete_ptr -.Fa "_STACK *stack" -.Fa "void *wanted" -.Fc -.Ft void -.Fo sk_zero -.Fa "_STACK *stack" -.Fc -.Sh DESCRIPTION -OpenSSL introduced an idiosyncratic concept of variable sized arrays -of pointers and somewhat misleadingly called such an array a -.Dq stack . -Intrinsically, and as documented in this manual page, OpenSSL stacks -are not type safe but only handle -.Vt void * -function arguments and return values. -.Pp -OpenSSL also provides a fragile, unusually complicated system of -macro-generated wrappers that offers superficial type safety at the -expense of extensive obfuscation, implemented using large amounts -of autogenerated code involving exceedingly ugly, nested -.Xr cpp 1 -macros; see the -.Xr STACK_OF 3 -manual page for details. -.Pp -The fundamental data type is the -.Vt _STACK -structure. -It stores a variable number of void pointers -and remembers the number of pointers currently stored. -It can optionally hold a pointer to a comparison function. -As long as no comparison function is installed, the order of pointers -is meaningful; as soon as a comparison function is installed, it -becomes ill-defined. -.Pp -.Fn sk_new_null -allocates and initializes a new, empty stack. -.Fn sk_new -is identical except that it also installs -.Fa compfunc -as the comparison function for the new stack object. -.Fn sk_set_cmp_func -installs -.Fa compfunc -for the existing -.Fa stack . -The -.Fa compfunc -is allowed to be -.Dv NULL , -but the -.Fa stack -is not. -.Pp -.Fn sk_dup -creates a shallow copy of the given -.Fa stack , -which must not be a -.Dv NULL -pointer. -It neither copies the objects pointed to from the stack nor -increases their reference counts, but merely copies the pointers. -Extreme care must be taken in order to avoid freeing the memory twice, -for example by calling -.Fn sk_free -on one copy and only calling -.Fn sk_pop_free -on the other. -.Pp -.Fn sk_free -frees the given -.Fa stack . -It does not free any of the pointers stored on the stack. -Unless these pointers are merely copies of pointers owned by -other objects, they must be freed before calling -.Fn sk_free , -in order to avoid leaking memory. -If -.Fa stack -is a -.Dv NULL -pointer, no action occurs. -.Pp -.Fn sk_pop_free -is severely misnamed. -It does not at all do what one would expect from a function called -.Dq pop . -Instead, it does the same as -.Fn sk_free , -except that it also calls the function -.Fa freefunc -on each of the pointers contained in the -.Fa stack . -If the calls to -.Fa freefunc -are intended to free the memory in use by the objects on the stack, -ensure that no other pointers to the same objects remain elsewhere. -.Pp -.Fn sk_find -searches the -.Fa stack -for the -.Fa wanted -pointer. -If the -.Fa stack -contains more than one copy of the -.Fa wanted -pointer, only the first match is found. -If a comparison function is installed for the stack, the stack is -first sorted with -.Fn sk_sort , -and instead of comparing pointers, two pointers are considered to match -if the comparison function returns 0. -.Pp -.Fn sk_sort -sorts the -.Fa stack -using -.Xr qsort 3 -and the installed comparison function. -If -.Fa stack -is a -.Dv NULL -pointer or already considered sorted, no action occurs. -This function can only be called if a comparison function is installed. -.Pp -.Fn sk_is_sorted -reports whether the -.Fa stack -is considered sorted. -Calling -.Fn sk_new_null -or -.Fn sk_new , -successfully calling -.Fn sk_push , -.Fn sk_unshift , -.Fn sk_insert , -or -.Fn sk_set , -or changing the comparison function sets the state to unsorted. -If a comparison function is installed, calling -.Fn sk_sort , -or -.Fn sk_find -sets the state to sorted. -.Pp -.Fn sk_push -pushes -.Fa new_item -onto the end of the -.Fa stack , -increasing the number of pointers by 1. -If -.Fa stack -is a -.Dv NULL -pointer, no action occurs. -.Pp -.Fn sk_unshift -inserts -.Fa new_item -at the beginning of the -.Fa stack , -such that it gets the index 0. -The number of pointers increases by 1. -If -.Fa stack -is a -.Dv NULL -pointer, no action occurs. -.Pp -.Fn sk_insert -inserts the -.Fa new_item -into the -.Fa stack -such that it gets the given -.Fa index . -If -.Fa index -is less than 0 or greater than or equal to -.Fn sk_num stack , -the effect is the same as for -.Fn sk_push . -If -.Fa stack -is a -.Dv NULL -pointer, no action occurs. -.Pp -.Fn sk_set -replaces the pointer with the given -.Fa index -on the -.Fa stack -with the -.Fa new_item . -The old pointer is not freed, -which may leak memory if no copy of it exists elsewhere. -If -.Fa stack -is a -.Dv NULL -pointer or if -.Fa index -is less than 0 or greater than or equal to -.Fn sk_num stack , -no action occurs. -.Pp -.Fn sk_pop -and -.Fn sk_shift -remove the pointer with the highest or lowest index from the -.Fa stack , -respectively, reducing the number of pointers by 1. -If -.Fa stack -is a -.Dv NULL -pointer or if it is empty, no action occurs. -.Pp -.Fn sk_delete -removes the pointer with the given -.Fa index -from the -.Fa stack , -reducing the number of pointers by 1. -If -.Fa stack -is a -.Dv NULL -pointer or the -.Fa index -is less than 0 or greater than or equal to -.Fn sk_num stack , -no action occurs. -.Pp -.Fn sk_delete_ptr -removes the -.Fa wanted -pointer from the -.Fa stack , -reducing the number of pointers by 1 if it is found. -It never uses a comparison function -but only compares pointers themselves. -The -.Fa stack -pointer must not be -.Dv NULL . -.Pp -.Fn sk_zero -removes all pointers from the -.Fa stack . -It does not free any of the pointers. -Unless these pointers are merely copies of pointers owned by other -objects, they must be freed before calling -.Fn sk_zero , -in order to avoid leaking memory. -If -.Fa stack -is a -.Dv NULL -pointer, no action occurs. -.Sh RETURN VALUES -.Fn sk_new_null , -.Fn sk_new , -and -.Fn sk_dup -return a pointer to the newly allocated stack object or -.Dv NULL -if insufficient memory is available. -.Pp -.Fn sk_set_cmp_func -returns a pointer to the comparison function -that was previously installed for the -.Fa stack -or -.Dv NULL -if none was installed. -.Pp -.Fn sk_num -returns the number of pointers currently stored on the -.Fa stack , -or \-1 if -.Fa stack -is a -.Dv NULL -pointer. -.Pp -.Fn sk_value -returns the pointer with the given -.Fa index -from the -.Fa stack , -or -.Dv NULL -if -.Fa stack -is a -.Dv NULL -pointer or if the -.Fa index -is less than 0 or greater than or equal to -.Fn sk_num stack . -.Pp -.Fn sk_find -returns the lowest index considered to match or \-1 if -.Fa stack -is a -.Dv NULL -pointer or if no match is found. -.Pp -.Fn sk_is_sorted -returns 1 if the -.Fa stack -is considered sorted or if it is a -.Dv NULL -pointer, or 0 otherwise. -.Pp -.Fn sk_push , -.Fn sk_unshift , -and -.Fn sk_insert -return the new number of pointers on the -.Fa stack -or 0 if -.Fa stack -is a -.Dv NULL -pointer or if memory allocation fails. -.Pp -.Fn sk_set -returns -.Fa new_item -or -.Dv NULL -if -.Fa stack -is a -.Dv NULL -pointer or if the -.Fa index -is less than 0 or greater than or equal to -.Fn sk_num stack . -.Pp -.Fn sk_pop -and -.Fn sk_shift -return the deleted pointer or -.Dv NULL -if -.Fa stack -is a -.Dv NULL -pointer or if it is empty. -.Pp -.Fn sk_delete -returns the deleted pointer or -.Dv NULL -if -.Fa stack -is a -.Dv NULL -pointer or if the -.Fa index -is less than 0 or greater than or equal to -.Fn sk_num stack . -.Pp -.Fn sk_delete_ptr -returns -.Fa wanted -or -.Dv NULL -if it is not found. -.Sh SEE ALSO -.Xr STACK_OF 3 -.Sh HISTORY -.Fn sk_new_null , -.Fn sk_new , -.Fn sk_free , -.Fn sk_pop_free , -.Fn sk_num , -.Fn sk_value , -.Fn sk_find , -.Fn sk_push , -.Fn sk_unshift , -.Fn sk_insert , -.Fn sk_pop , -.Fn sk_shift , -.Fn sk_delete , -and -.Fn sk_delete_ptr -first appeared in SSLeay 0.5.1. -.Fn sk_set_cmp_func , -.Fn sk_dup , -and -.Fn sk_zero -first appeared in SSLeay 0.8.0. -These functions have been available since -.Ox 2.4 . -.Pp -.Fn sk_set -first appeared in OpenSSL 0.9.3. -.Fn sk_sort -first appeared in OpenSSL 0.9.4. -Both functions have been available since -.Ox 2.6 . -.Pp -.Fn sk_is_sorted -first appeared in OpenSSL 0.9.7e and has been available since -.Ox 3.8 . -.Sh BUGS -Even if a comparison function is installed, empty stacks and -stacks containing a single pointer are sometimes considered -sorted and sometimes considered unsorted. -.Pp -If a comparison function is installed, the concept of -.Dq first match -in -.Fn sk_find -is ill-defined because -.Xr qsort 3 -is not a stable sorting function. -It is probably best to only assume that they return an arbitrary match. -- cgit v1.2.3-55-g6feb