Commit d1f8b74c authored by Andy Polyakov's avatar Andy Polyakov
Browse files

man3/OPENSSL_LH_COMPFUNC.pod: clarifications and updates. 



Reviewed-by: default avatarPaul Dale <paul.dale@oracle.com>
Reviewed-by: default avatarRich Salz <rsalz@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/6786)
parent f21b5b64

doc/man3/OPENSSL_LH_COMPFUNC.pod

+9 −16
Original line number Diff line number Diff line
@@ -18,7 +18,7 @@ lh_TYPE_doall, lh_TYPE_doall_arg, lh_TYPE_error - dynamic hash table 


 DECLARE_LHASH_OF(TYPE);



 LHASH *lh_TYPE_new();

 LHASH *lh_TYPE_new(OPENSSL_LH_HASHFUNC hash, OPENSSL_LH_COMPFUNC compare);

 void lh_TYPE_free(LHASH_OF(TYPE) *table);



 TYPE *lh_TYPE_insert(LHASH_OF(TYPE) *table, TYPE *data);
@@ -27,7 +27,7 @@ lh_TYPE_doall, lh_TYPE_doall_arg, lh_TYPE_error - dynamic hash table 


 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,

          TYPE, TYPE *arg);

                        TYPE *arg);



 int lh_TYPE_error(LHASH_OF(TYPE) *table);
@@ -171,25 +171,18 @@ lh_TYPE_retrieve() returns the hash table entry if it has been found, 
B<NULL> otherwise.



lh_TYPE_error() returns 1 if an error occurred in the last operation, 0

otherwise.

otherwise. It's meaningful only after non-retrieve operations.



lh_TYPE_free(), lh_TYPE_doall() and lh_TYPE_doall_arg() return no values.



=head1 NOTE



The various LHASH macros and callback types exist to make it possible

to write type-checked code without resorting to function-prototype

casting - an evil that makes application code much harder to

audit/verify and also opens the window of opportunity for stack

corruption and other hard-to-find bugs.  It also, apparently, violates

ANSI-C.



The LHASH code is not thread safe. All updating operations 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 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, 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 *"