Document OPENSSL_LH_flush()

The function OPENSSL_LH_flush() was added since 1.1.1 and was
undocumented. We also add documentation for some other OPENSSL_LH_*()
functions at the same time.

Reviewed-by: Paul Dale <pauli@openssl.org>
Reviewed-by: Tomas Mraz <tomas@openssl.org>
Reviewed-by: Richard Levitte <levitte@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/14232)

diff --git a/doc/man3/OPENSSL_LH_COMPFUNC.pod b/doc/man3/OPENSSL_LH_COMPFUNC.pod
index 3873ac0031865c1bb9b22264b7184100a5f1cefb..c109601597b3249b0477e66b8e52f7b61797a35c 100644 (file)
--- a/doc/man3/OPENSSL_LH_COMPFUNC.pod
+++ b/doc/man3/OPENSSL_LH_COMPFUNC.pod
@@ -8,7 +8,11 @@ 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 - dynamic hash table
+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
 
 =head1 SYNOPSIS
 
@@ -18,7 +22,7 @@ lh_TYPE_doall, lh_TYPE_doall_arg, lh_TYPE_error - dynamic hash table
 
  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);
 
@@ -37,6 +41,19 @@ lh_TYPE_doall, lh_TYPE_doall_arg, lh_TYPE_error - dynamic hash table
  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);
+
 =head1 DESCRIPTION
 
 This library implements type-checked dynamic hash tables. The hash
@@ -162,34 +179,50 @@ that is provided by the caller):
 B<lh_I<TYPE>_error>() can be used to determine if an error occurred in the last
 operation.
 
+OPENSSL_LH_new() is the same as the B<lh_I<TYPE>_new>() except that it is not
+type specific. So instead of returning an B<LHASH_OF(I<TYPE>)> value it returns
+a B<void *>. In the same way the functions OPENSSL_LH_free(),
+OPENSSL_LH_flush(), OPENSSL_LH_insert(), OPENSSL_LH_delete(),
+OPENSSL_LH_retrieve(), OPENSSL_LH_doall(), OPENSSL_LH_doall_arg(), and
+OPENSSL_LH_error() are equivalent to the similarly named B<lh_I<TYPE>> functions
+except that they return or use a B<void *> where the equivalent B<lh_I<TYPE>>
+function returns or uses a B<I<TYPE> *> or B<LHASH_OF(I<TYPE>) *>. B<lh_I<TYPE>>
+functions are implemented as type checked wrappers around the B<OPENSSL_LH>
+functions. Most applications should not call the B<OPENSSL_LH> functions
+directly.
+
 =head1 RETURN VALUES
 
-B<lh_I<TYPE>_new>() returns NULL on error, otherwise a pointer to the new
-B<LHASH> structure.
+B<lh_I<TYPE>_new>() and OPENSSL_LH_new() return NULL on error, otherwise a
+pointer to the new B<LHASH> structure.
 
-When a hash table entry is replaced, B<lh_I<TYPE>_insert>() returns the value
-being replaced. NULL is returned on normal operation and on error.
+When a hash table entry is replaced, B<lh_I<TYPE>_insert>() or
+OPENSSL_LH_insert() return the value being replaced. NULL is returned on normal
+operation and on error.
 
-B<lh_I<TYPE>_delete>() returns the entry being deleted.  NULL is returned if
-there is no such value in the hash table.
+B<lh_I<TYPE>_delete>() and OPENSSL_LH_delete() return the entry being deleted.
+NULL is returned if there is no such value in the hash table.
 
-B<lh_I<TYPE>_retrieve>() returns the hash table entry if it has been found,
-NULL otherwise.
+B<lh_I<TYPE>_retrieve>() and OPENSSL_LH_retrieve() return the hash table entry
+if it has been found, NULL otherwise.
 
-B<lh_I<TYPE>_error>() returns 1 if an error occurred in the last operation, 0
-otherwise. It's meaningful only after non-retrieve operations.
+B<lh_I<TYPE>_error>() and OPENSSL_LH_error() return 1 if an error occurred in
+the last operation, 0 otherwise. It's meaningful only after non-retrieve
+operations.
 
-B<lh_I<TYPE>_free>(), B<lh_I<TYPE>_flush>(), B<lh_I<TYPE>_doall>() and
-B<lh_I<TYPE>_doall_arg>() return no values.
+B<lh_I<TYPE>_free>(), OPENSSL_LH_free(), B<lh_I<TYPE>_flush>(),
+OPENSSL_LH_flush(), B<lh_I<TYPE>_doall>() OPENSSL_LH_doall(),
+B<lh_I<TYPE>_doall_arg>() and OPENSSL_LH_doall_arg() return no values.
 
 =head1 NOTE
 
 The LHASH code is not thread safe. All updating operations, as well as
-B<lh_I<TYPE>_error>() call must be performed under a write lock. All retrieve
-operations should be performed under a read lock, I<unless> 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 L<OPENSSL_LH_stats(3)>, a read lock suffices.
+B<lh_I<TYPE>_error>() or OPENSSL_LH_error() calls must be performed under
+a write lock. All retrieve operations should be performed under a read lock,
+I<unless> 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 L<OPENSSL_LH_stats(3)>, a read lock
+suffices.
 
 The LHASH code regards table entries as constant data.  As such, it
 internally represents lh_insert()'d items with a "const void *"
@@ -223,7 +256,8 @@ without any "const" qualifiers.
 
 =head1 BUGS
 
-B<lh_I<TYPE>_insert>() returns NULL both for success and error.
+B<lh_I<TYPE>_insert>() and OPENSSL_LH_insert() return NULL both for success
+and error.
 
 =head1 SEE ALSO
 

diff --git a/util/missingcrypto.txt b/util/missingcrypto.txt
index 85f03fc9cc0071a1b7d62f8570826fc73891b73e..61d91b0c928813f38525563f41d7b26a701ceefd 100644 (file)
--- a/util/missingcrypto.txt
+++ b/util/missingcrypto.txt
@@ -837,17 +837,8 @@ OCSP_response_status_str(3)
 OCSP_url_svcloc_new(3)
 OPENSSL_DIR_end(3)
 OPENSSL_DIR_read(3)
-OPENSSL_LH_delete(3)
-OPENSSL_LH_doall(3)
-OPENSSL_LH_doall_arg(3)
-OPENSSL_LH_error(3)
-OPENSSL_LH_flush(3)
-OPENSSL_LH_free(3)
 OPENSSL_LH_get_down_load(3)
-OPENSSL_LH_insert(3)
-OPENSSL_LH_new(3)
 OPENSSL_LH_num_items(3)
-OPENSSL_LH_retrieve(3)
 OPENSSL_LH_set_down_load(3)
 OPENSSL_LH_strhash(3)
 OPENSSL_asc2uni(3)