diff options
author | Matt Caswell <matt@openssl.org> | 2021-02-17 17:06:41 +0000 |
---|---|---|
committer | Matt Caswell <matt@openssl.org> | 2021-02-22 12:15:34 +0000 |
commit | 7e1d7fea395654fd169bdb3d01b2f56236ed13c1 (patch) | |
tree | 42c6708112aeb56a60898bc2d17b18383ce1a181 /doc | |
parent | bc4d84abce0e08e84078f9113c2f3d555b52d317 (diff) |
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)
Diffstat (limited to 'doc')
-rw-r--r-- | doc/man3/OPENSSL_LH_COMPFUNC.pod | 74 |
1 files changed, 54 insertions, 20 deletions
diff --git a/doc/man3/OPENSSL_LH_COMPFUNC.pod b/doc/man3/OPENSSL_LH_COMPFUNC.pod index 3873ac0031..c109601597 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<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 |