1 files changed, 95 insertions, 50 deletions
diff --git a/secure/lib/libcrypto/man/man3/OPENSSL_LH_COMPFUNC.3 b/secure/lib/libcrypto/man/man3/OPENSSL_LH_COMPFUNC.3
index c18793b882a5..c0f84876956d 100644
--- a/secure/lib/libcrypto/man/man3/OPENSSL_LH_COMPFUNC.3
+++ b/secure/lib/libcrypto/man/man3/OPENSSL_LH_COMPFUNC.3
@@ -1,4 +1,4 @@
-.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
+.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
 .\"
 .\" Standard preamble:
 .\" ========================================================================
@@ -68,8 +68,6 @@
 .    \}
 .\}
 .rr rF
-.\"
-.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
 .    \" fudge factors for nroff and troff
 .if n \{\
@@ -132,14 +130,24 @@
 .rm #[ #] #H #V #F C
 .\" ========================================================================
 .\"
-.IX Title "OPENSSL_LH_COMPFUNC 3"
-.TH OPENSSL_LH_COMPFUNC 3 "2022-07-05" "1.1.1q" "OpenSSL"
+.IX Title "OPENSSL_LH_COMPFUNC 3ossl"
+.TH OPENSSL_LH_COMPFUNC 3ossl "2023-09-19" "3.0.11" "OpenSSL"
 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 .\" way too many mistakes in technical documents.
 .if n .ad l
 .nh
 .SH "NAME"
-LHASH, DECLARE_LHASH_OF, OPENSSL_LH_COMPFUNC, OPENSSL_LH_HASHFUNC, OPENSSL_LH_DOALL_FUNC, LHASH_DOALL_ARG_FN_TYPE, IMPLEMENT_LHASH_HASH_FN, IMPLEMENT_LHASH_COMP_FN, lh_TYPE_new, lh_TYPE_free, lh_TYPE_insert, lh_TYPE_delete, lh_TYPE_retrieve, lh_TYPE_doall, lh_TYPE_doall_arg, lh_TYPE_error \- dynamic hash table
+LHASH, DECLARE_LHASH_OF,
+OPENSSL_LH_COMPFUNC, OPENSSL_LH_HASHFUNC, OPENSSL_LH_DOALL_FUNC,
+LHASH_DOALL_ARG_FN_TYPE,
+IMPLEMENT_LHASH_HASH_FN, IMPLEMENT_LHASH_COMP_FN,
+lh_TYPE_new, lh_TYPE_free, lh_TYPE_flush,
+lh_TYPE_insert, lh_TYPE_delete, lh_TYPE_retrieve,
+lh_TYPE_doall, lh_TYPE_doall_arg, lh_TYPE_error,
+OPENSSL_LH_new, OPENSSL_LH_free,  OPENSSL_LH_flush,
+OPENSSL_LH_insert, OPENSSL_LH_delete, OPENSSL_LH_retrieve,
+OPENSSL_LH_doall, OPENSSL_LH_doall_arg, OPENSSL_LH_error
+\&\- dynamic hash table
 .SH "SYNOPSIS"
 .IX Header "SYNOPSIS"
 .Vb 1
@@ -147,12 +155,13 @@ LHASH, DECLARE_LHASH_OF, OPENSSL_LH_COMPFUNC, OPENSSL_LH_HASHFUNC, OPENSSL_LH_DO
 \&
 \& DECLARE_LHASH_OF(TYPE);
 \&
-\& LHASH *lh_TYPE_new(OPENSSL_LH_HASHFUNC hash, OPENSSL_LH_COMPFUNC compare);
+\& LHASH_OF(TYPE) *lh_TYPE_new(OPENSSL_LH_HASHFUNC hash, OPENSSL_LH_COMPFUNC compare);
 \& void lh_TYPE_free(LHASH_OF(TYPE) *table);
+\& void lh_TYPE_flush(LHASH_OF(TYPE) *table);
 \&
 \& TYPE *lh_TYPE_insert(LHASH_OF(TYPE) *table, TYPE *data);
 \& TYPE *lh_TYPE_delete(LHASH_OF(TYPE) *table, TYPE *data);
-\& TYPE *lh_retrieve(LHASH_OF(TYPE) *table, TYPE *data);
+\& TYPE *lh_TYPE_retrieve(LHASH_OF(TYPE) *table, TYPE *data);
 \&
 \& void lh_TYPE_doall(LHASH_OF(TYPE) *table, OPENSSL_LH_DOALL_FUNC func);
 \& void lh_TYPE_doall_arg(LHASH_OF(TYPE) *table, OPENSSL_LH_DOALL_FUNCARG func,
@@ -164,30 +173,43 @@ LHASH, DECLARE_LHASH_OF, OPENSSL_LH_COMPFUNC, OPENSSL_LH_HASHFUNC, OPENSSL_LH_DO
 \& typedef unsigned long (*OPENSSL_LH_HASHFUNC)(const void *);
 \& typedef void (*OPENSSL_LH_DOALL_FUNC)(const void *);
 \& typedef void (*LHASH_DOALL_ARG_FN_TYPE)(const void *, const void *);
+\&
+\& OPENSSL_LHASH *OPENSSL_LH_new(OPENSSL_LH_HASHFUNC h, OPENSSL_LH_COMPFUNC c);
+\& void OPENSSL_LH_free(OPENSSL_LHASH *lh);
+\& void OPENSSL_LH_flush(OPENSSL_LHASH *lh);
+\&
+\& void *OPENSSL_LH_insert(OPENSSL_LHASH *lh, void *data);
+\& void *OPENSSL_LH_delete(OPENSSL_LHASH *lh, const void *data);
+\& void *OPENSSL_LH_retrieve(OPENSSL_LHASH *lh, const void *data);
+\&
+\& void OPENSSL_LH_doall(OPENSSL_LHASH *lh, OPENSSL_LH_DOALL_FUNC func);
+\& void OPENSSL_LH_doall_arg(OPENSSL_LHASH *lh, OPENSSL_LH_DOALL_FUNCARG func, void *arg);
+\&
+\& int OPENSSL_LH_error(OPENSSL_LHASH *lh);
 .Ve
 .SH "DESCRIPTION"
 .IX Header "DESCRIPTION"
 This library implements type-checked dynamic hash tables. The hash
 table entries can be arbitrary structures. Usually they consist of key
-and value fields.  In the description here, \fI\s-1TYPE\s0\fR is used a placeholder
+and value fields.  In the description here, \fB\f(BI\s-1TYPE\s0\fB\fR is used a placeholder
 for any of the OpenSSL datatypes, such as \fI\s-1SSL_SESSION\s0\fR.
 .PP
-\&\fBlh_TYPE_new()\fR creates a new \fB\s-1LHASH_OF\s0(\s-1TYPE\s0)\fR structure to store
+\&\fBlh_\f(BI\s-1TYPE\s0\fB_new\fR() creates a new \fB\s-1LHASH_OF\s0\fR(\fB\f(BI\s-1TYPE\s0\fB\fR) structure to store
 arbitrary data entries, and specifies the 'hash' and 'compare'
-callbacks to be used in organising the table's entries.  The \fBhash\fR
+callbacks to be used in organising the table's entries.  The \fIhash\fR
 callback takes a pointer to a table entry as its argument and returns
 an unsigned long hash value for its key field.  The hash value is
 normally truncated to a power of 2, so make sure that your hash
-function returns well mixed low order bits.  The \fBcompare\fR callback
+function returns well mixed low order bits.  The \fIcompare\fR callback
 takes two arguments (pointers to two hash table entries), and returns
 0 if their keys are equal, nonzero otherwise.
 .PP
 If your hash table
-will contain items of some particular type and the \fBhash\fR and
-\&\fBcompare\fR callbacks hash/compare these types, then the
+will contain items of some particular type and the \fIhash\fR and
+\&\fIcompare\fR callbacks hash/compare these types, then the
 \&\fB\s-1IMPLEMENT_LHASH_HASH_FN\s0\fR and \fB\s-1IMPLEMENT_LHASH_COMP_FN\s0\fR macros can be
 used to create callback wrappers of the prototypes required by
-\&\fBlh_TYPE_new()\fR as shown in this example:
+\&\fBlh_\f(BI\s-1TYPE\s0\fB_new\fR() as shown in this example:
 .PP
 .Vb 11
 \& /*
@@ -217,32 +239,37 @@ can be used in a common header file to declare the function wrappers:
 \& DECLARE_LHASH_COMP_FN(stuff, TYPE)
 .Ve
 .PP
-Then a hash table of \s-1TYPE\s0 objects can be created using this:
+Then a hash table of \fB\f(BI\s-1TYPE\s0\fB\fR objects can be created using this:
 .PP
 .Vb 1
 \& LHASH_OF(TYPE) *htable;
 \&
-\& htable = lh_TYPE_new(LHASH_HASH_FN(stuff), LHASH_COMP_FN(stuff));
+\& htable = B<lh_I<TYPE>_new>(LHASH_HASH_FN(stuff), LHASH_COMP_FN(stuff));
 .Ve
 .PP
-\&\fBlh_TYPE_free()\fR frees the \fB\s-1LHASH_OF\s0(\s-1TYPE\s0)\fR structure
-\&\fBtable\fR. Allocated hash table entries will not be freed; consider
-using \fBlh_TYPE_doall()\fR to deallocate any remaining entries in the
+\&\fBlh_\f(BI\s-1TYPE\s0\fB_free\fR() frees the \fB\s-1LHASH_OF\s0\fR(\fB\f(BI\s-1TYPE\s0\fB\fR) structure
+\&\fItable\fR. Allocated hash table entries will not be freed; consider
+using \fBlh_\f(BI\s-1TYPE\s0\fB_doall\fR() to deallocate any remaining entries in the
 hash table (see below).
 .PP
-\&\fBlh_TYPE_insert()\fR inserts the structure pointed to by \fBdata\fR into
-\&\fBtable\fR.  If there already is an entry with the same key, the old
-value is replaced. Note that \fBlh_TYPE_insert()\fR stores pointers, the
+\&\fBlh_\f(BI\s-1TYPE\s0\fB_flush\fR() empties the \fB\s-1LHASH_OF\s0\fR(\fB\f(BI\s-1TYPE\s0\fB\fR) structure \fItable\fR. New
+entries can be added to the flushed table.  Allocated hash table entries
+will not be freed; consider using \fBlh_\f(BI\s-1TYPE\s0\fB_doall\fR() to deallocate any
+remaining entries in the hash table (see below).
+.PP
+\&\fBlh_\f(BI\s-1TYPE\s0\fB_insert\fR() inserts the structure pointed to by \fIdata\fR into
+\&\fItable\fR.  If there already is an entry with the same key, the old
+value is replaced. Note that \fBlh_\f(BI\s-1TYPE\s0\fB_insert\fR() stores pointers, the
 data are not copied.
 .PP
-\&\fBlh_TYPE_delete()\fR deletes an entry from \fBtable\fR.
+\&\fBlh_\f(BI\s-1TYPE\s0\fB_delete\fR() deletes an entry from \fItable\fR.
 .PP
-\&\fBlh_TYPE_retrieve()\fR looks up an entry in \fBtable\fR. Normally, \fBdata\fR
+\&\fBlh_\f(BI\s-1TYPE\s0\fB_retrieve\fR() looks up an entry in \fItable\fR. Normally, \fIdata\fR
 is a structure with the key field(s) set; the function will return a
 pointer to a fully populated structure.
 .PP
-\&\fBlh_TYPE_doall()\fR will, for every entry in the hash table, call
-\&\fBfunc\fR with the data item as its parameter.
+\&\fBlh_\f(BI\s-1TYPE\s0\fB_doall\fR() will, for every entry in the hash table, call
+\&\fIfunc\fR with the data item as its parameter.
 For example:
 .PP
 .Vb 2
@@ -268,9 +295,9 @@ you start (which will stop the hash table ever decreasing in size).
 The best solution is probably to avoid deleting items from the hash
 table inside a \*(L"doall\*(R" callback!
 .PP
-\&\fBlh_TYPE_doall_arg()\fR is the same as \fBlh_TYPE_doall()\fR except that
-\&\fBfunc\fR will be called with \fBarg\fR as the second argument and \fBfunc\fR
-should be of type \fB\s-1LHASH_DOALL_ARG_FN_TYPE\s0\fR (a callback prototype
+\&\fBlh_\f(BI\s-1TYPE\s0\fB_doall_arg\fR() is the same as \fBlh_\f(BI\s-1TYPE\s0\fB_doall\fR() except that
+\&\fIfunc\fR will be called with \fIarg\fR as the second argument and \fIfunc\fR
+should be of type \fB\s-1LHASH_DOALL_ARG_FN\s0\fR(\fB\f(BI\s-1TYPE\s0\fB\fR) (a callback prototype
 that is passed both the table entry and an extra argument).  As with
 \&\fBlh_doall()\fR, you can instead choose to declare your callback with a
 prototype matching the types you are dealing with and use the
@@ -291,34 +318,51 @@ that is provided by the caller):
 \&                   logging_bio);
 .Ve
 .PP
-\&\fBlh_TYPE_error()\fR can be used to determine if an error occurred in the last
+\&\fBlh_\f(BI\s-1TYPE\s0\fB_error\fR() can be used to determine if an error occurred in the last
 operation.
+.PP
+\&\fBOPENSSL_LH_new()\fR is the same as the \fBlh_\f(BI\s-1TYPE\s0\fB_new\fR() except that it is not
+type specific. So instead of returning an \fB\s-1LHASH_OF\s0(\f(BI\s-1TYPE\s0\fB)\fR value it returns
+a \fBvoid *\fR. In the same way the functions \fBOPENSSL_LH_free()\fR,
+\&\fBOPENSSL_LH_flush()\fR, \fBOPENSSL_LH_insert()\fR, \fBOPENSSL_LH_delete()\fR,
+\&\fBOPENSSL_LH_retrieve()\fR, \fBOPENSSL_LH_doall()\fR, \fBOPENSSL_LH_doall_arg()\fR, and
+\&\fBOPENSSL_LH_error()\fR are equivalent to the similarly named \fBlh_\f(BI\s-1TYPE\s0\fB\fR functions
+except that they return or use a \fBvoid *\fR where the equivalent \fBlh_\f(BI\s-1TYPE\s0\fB\fR
+function returns or uses a \fB\f(BI\s-1TYPE\s0\fB *\fR or \fB\s-1LHASH_OF\s0(\f(BI\s-1TYPE\s0\fB) *\fR. \fBlh_\f(BI\s-1TYPE\s0\fB\fR
+functions are implemented as type checked wrappers around the \fB\s-1OPENSSL_LH\s0\fR
+functions. Most applications should not call the \fB\s-1OPENSSL_LH\s0\fR functions
+directly.
 .SH "RETURN VALUES"
 .IX Header "RETURN VALUES"
-\&\fBlh_TYPE_new()\fR returns \fB\s-1NULL\s0\fR on error, otherwise a pointer to the new
-\&\fB\s-1LHASH\s0\fR structure.
+\&\fBlh_\f(BI\s-1TYPE\s0\fB_new\fR() and \fBOPENSSL_LH_new()\fR return \s-1NULL\s0 on error, otherwise a
+pointer to the new \fB\s-1LHASH\s0\fR structure.
 .PP
-When a hash table entry is replaced, \fBlh_TYPE_insert()\fR returns the value
-being replaced. \fB\s-1NULL\s0\fR is returned on normal operation and on error.
+When a hash table entry is replaced, \fBlh_\f(BI\s-1TYPE\s0\fB_insert\fR() or
+\&\fBOPENSSL_LH_insert()\fR return the value being replaced. \s-1NULL\s0 is returned on normal
+operation and on error.
 .PP
-\&\fBlh_TYPE_delete()\fR returns the entry being deleted.  \fB\s-1NULL\s0\fR is returned if
-there is no such value in the hash table.
+\&\fBlh_\f(BI\s-1TYPE\s0\fB_delete\fR() and \fBOPENSSL_LH_delete()\fR return the entry being deleted.
+\&\s-1NULL\s0 is returned if there is no such value in the hash table.
 .PP
-\&\fBlh_TYPE_retrieve()\fR returns the hash table entry if it has been found,
-\&\fB\s-1NULL\s0\fR otherwise.
+\&\fBlh_\f(BI\s-1TYPE\s0\fB_retrieve\fR() and \fBOPENSSL_LH_retrieve()\fR return the hash table entry
+if it has been found, \s-1NULL\s0 otherwise.
 .PP
-\&\fBlh_TYPE_error()\fR returns 1 if an error occurred in the last operation, 0
-otherwise. It's meaningful only after non-retrieve operations.
+\&\fBlh_\f(BI\s-1TYPE\s0\fB_error\fR() and \fBOPENSSL_LH_error()\fR return 1 if an error occurred in
+the last operation, 0 otherwise. It's meaningful only after non-retrieve
+operations.
 .PP
-\&\fBlh_TYPE_free()\fR, \fBlh_TYPE_doall()\fR and \fBlh_TYPE_doall_arg()\fR return no values.
+\&\fBlh_\f(BI\s-1TYPE\s0\fB_free\fR(), \fBOPENSSL_LH_free()\fR, \fBlh_\f(BI\s-1TYPE\s0\fB_flush\fR(),
+\&\fBOPENSSL_LH_flush()\fR, \fBlh_\f(BI\s-1TYPE\s0\fB_doall\fR() \fBOPENSSL_LH_doall()\fR,
+\&\fBlh_\f(BI\s-1TYPE\s0\fB_doall_arg\fR() and \fBOPENSSL_LH_doall_arg()\fR return no values.
 .SH "NOTE"
 .IX Header "NOTE"
 The \s-1LHASH\s0 code is not thread safe. All updating operations, as well as
-lh_TYPE_error call must be performed under a write lock. All retrieve
-operations should be performed under a read lock, \fIunless\fR accurate
-usage statistics are desired. In which case, a write lock should be used
-for retrieve operations as well. For output of the usage statistics,
-using the functions from \fBOPENSSL_LH_stats\fR\|(3), a read lock suffices.
+\&\fBlh_\f(BI\s-1TYPE\s0\fB_error\fR() or \fBOPENSSL_LH_error()\fR calls must be performed under
+a write lock. All retrieve operations should be performed under a read lock,
+\&\fIunless\fR accurate usage statistics are desired. In which case, a write lock
+should be used for retrieve operations as well. For output of the usage
+statistics, using the functions from \fBOPENSSL_LH_stats\fR\|(3), a read lock
+suffices.
 .PP
 The \s-1LHASH\s0 code regards table entries as constant data.  As such, it
 internally represents \fBlh_insert()\fR'd items with a \*(L"const void *\*(R"
@@ -351,7 +395,8 @@ DECLARE/IMPLEMENT_LHASH_DOALL_[\s-1ARG_\s0]_FN macros that provide types
 without any \*(L"const\*(R" qualifiers.
 .SH "BUGS"
 .IX Header "BUGS"
-\&\fBlh_TYPE_insert()\fR returns \fB\s-1NULL\s0\fR both for success and error.
+\&\fBlh_\f(BI\s-1TYPE\s0\fB_insert\fR() and \fBOPENSSL_LH_insert()\fR return \s-1NULL\s0 both for success
+and error.
 .SH "SEE ALSO"
 .IX Header "SEE ALSO"
 \&\fBOPENSSL_LH_stats\fR\|(3)
@@ -361,9 +406,9 @@ In OpenSSL 1.0.0, the lhash interface was revamped for better
 type checking.
 .SH "COPYRIGHT"
 .IX Header "COPYRIGHT"
-Copyright 2000\-2020 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2000\-2022 The OpenSSL Project Authors. All Rights Reserved.
 .PP
-Licensed under the OpenSSL license (the \*(L"License\*(R").  You may not use
+Licensed under the Apache License 2.0 (the \*(L"License\*(R").  You may not use
 this file except in compliance with the License.  You can obtain a copy
 in the file \s-1LICENSE\s0 in the source distribution or at
 <https://www.openssl.org/source/license.html>.