From d1f8b74c584d55a3c7f8f88d997ad69b67076c77 Mon Sep 17 00:00:00 2001 From: Andy Polyakov Date: Sun, 29 Jul 2018 15:21:38 +0200 Subject: [PATCH] man3/OPENSSL_LH_COMPFUNC.pod: clarifications and updates. Reviewed-by: Paul Dale Reviewed-by: Rich Salz (Merged from https://github.com/openssl/openssl/pull/6786) --- doc/man3/OPENSSL_LH_COMPFUNC.pod | 25 +++++++++---------------- 1 file changed, 9 insertions(+), 16 deletions(-) diff --git a/doc/man3/OPENSSL_LH_COMPFUNC.pod b/doc/man3/OPENSSL_LH_COMPFUNC.pod index ec21c79cad..a312ef7342 100644 --- a/doc/man3/OPENSSL_LH_COMPFUNC.pod +++ b/doc/man3/OPENSSL_LH_COMPFUNC.pod @@ -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 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 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 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 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 *" -- 2.25.1