From: Matt Caswell Date: Wed, 17 Feb 2021 17:06:41 +0000 (+0000) Subject: Document OPENSSL_LH_flush() X-Git-Tag: openssl-3.0.0-alpha13~241 X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=7e1d7fea395654fd169bdb3d01b2f56236ed13c1;p=thirdparty%2Fopenssl.git 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 Reviewed-by: Tomas Mraz Reviewed-by: Richard Levitte (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 3873ac00318..c109601597b 100644 --- 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_error>() can be used to determine if an error occurred in the last operation. +OPENSSL_LH_new() is the same as the B_new>() except that it is not +type specific. So instead of returning an B)> value it returns +a B. 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> functions +except that they return or use a B where the equivalent B> +function returns or uses a B *> or B) *>. B> +functions are implemented as type checked wrappers around the B +functions. Most applications should not call the B functions +directly. + =head1 RETURN VALUES -B_new>() returns NULL on error, otherwise a pointer to the new -B structure. +B_new>() and OPENSSL_LH_new() return NULL on error, otherwise a +pointer to the new B structure. -When a hash table entry is replaced, B_insert>() returns the value -being replaced. NULL is returned on normal operation and on error. +When a hash table entry is replaced, B_insert>() or +OPENSSL_LH_insert() return the value being replaced. NULL is returned on normal +operation and on error. -B_delete>() returns the entry being deleted. NULL is returned if -there is no such value in the hash table. +B_delete>() and OPENSSL_LH_delete() return the entry being deleted. +NULL is returned if there is no such value in the hash table. -B_retrieve>() returns the hash table entry if it has been found, -NULL otherwise. +B_retrieve>() and OPENSSL_LH_retrieve() return the hash table entry +if it has been found, NULL otherwise. -B_error>() returns 1 if an error occurred in the last operation, 0 -otherwise. It's meaningful only after non-retrieve operations. +B_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_free>(), B_flush>(), B_doall>() and -B_doall_arg>() return no values. +B_free>(), OPENSSL_LH_free(), B_flush>(), +OPENSSL_LH_flush(), B_doall>() OPENSSL_LH_doall(), +B_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_error>() call must be performed under a write lock. All retrieve -operations should be performed under a read lock, I 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, a read lock suffices. +B_error>() or OPENSSL_LH_error() calls must be performed under +a write lock. All retrieve operations should be performed under a read lock, +I 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, 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_insert>() returns NULL both for success and error. +B_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 85f03fc9cc0..61d91b0c928 100644 --- 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)