diff options
Diffstat (limited to 'doc/crypto/lhash.pod')
-rw-r--r-- | doc/crypto/lhash.pod | 84 |
1 files changed, 43 insertions, 41 deletions
diff --git a/doc/crypto/lhash.pod b/doc/crypto/lhash.pod index acc0821a35..9e29617e1b 100644 --- a/doc/crypto/lhash.pod +++ b/doc/crypto/lhash.pod @@ -2,39 +2,45 @@ =head1 NAME -lh_new, lh_free, lh_insert, lh_delete, lh_retrieve, lh_doall, lh_doall_arg, lh_error - dynamic hash table +DECLARE_LHASH_OF, +OPENSSL_LH_COMPFUNC, OPENSSL_LH_HASHFUNC, OPENSSL_LH_DOALL_FUNC, +LHASH_DOALL_ARG_FN_TYPE, +lh_TYPE_new, lh_TYPE_free, +lh_TYPE_insert, lh_TYPE_delete, lh_TYPE_retrieve, +lh_TYPE_doall, lh_TYPE_doall_arg, lh_TYPE_error - dynamic hash table =head1 SYNOPSIS #include <openssl/lhash.h> - DECLARE_LHASH_OF(<type>); + DECLARE_LHASH_OF(TYPE); - LHASH *lh_<type>_new(); - void lh_<type>_free(LHASH_OF(<type> *table); + LHASH *lh_TYPE_new(); + void lh_TYPE_free(LHASH_OF(TYPE *table); - <type> *lh_<type>_insert(LHASH_OF(<type> *table, <type> *data); - <type> *lh_<type>_delete(LHASH_OF(<type> *table, <type> *data); - <type> *lh_retrieve(LHASH_OF<type> *table, <type> *data); + TYPE *lh_TYPE_insert(LHASH_OF(TYPE *table, TYPE *data); + TYPE *lh_TYPE_delete(LHASH_OF(TYPE *table, TYPE *data); + TYPE *lh_retrieve(LHASH_OFTYPE *table, TYPE *data); - void lh_<type>_doall(LHASH_OF(<type> *table, LHASH_DOALL_FN_TYPE func); - void lh_<type>_doall_arg(LHASH_OF(<type> *table, LHASH_DOALL_ARG_FN_TYPE func, - <type2>, <type2> *arg); + 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); - int lh_<type>_error(LHASH_OF(<type> *table); + int lh_TYPE_error(LHASH_OF(TYPE) *table); - typedef int (*LHASH_COMP_FN_TYPE)(const void *, const void *); - typedef unsigned long (*LHASH_HASH_FN_TYPE)(const void *); - typedef void (*LHASH_DOALL_FN_TYPE)(const void *); + typedef int (*OPENSSL_LH_COMPFUNC)(const void *, const void *); + typedef unsigned long (*OPENSSL_LH_HASHFUNC)(const void *); + typedef void (*OPENSSL_LH_DOALL_FUNC)(const void *); typedef void (*LHASH_DOALL_ARG_FN_TYPE)(const void *, const void *); =head1 DESCRIPTION This library implements type-checked dynamic hash tables. The hash table entries can be arbitrary structures. Usually they consist of key -and value fields. +and value fields. In the description here, I<TYPE> is used a placeholder +for any of the OpenSSL datatypes, such as I<SSL_SESSION>. -lh_<type>_new() creates a new B<LHASH_OF(<type>> structure to store +lh_TYPE_new() creates a new B<LHASH_OF(TYPE)> structure to store arbitrary data entries, and provides the 'hash' and 'compare' callbacks to be used in organising the table's entries. The B<hash> callback takes a pointer to a table entry as its argument and returns @@ -47,7 +53,7 @@ will contain items of some particular type and the B<hash> and B<compare> callbacks hash/compare these types, then the B<DECLARE_LHASH_HASH_FN> and B<IMPLEMENT_LHASH_COMP_FN> macros can be used to create callback wrappers of the prototypes required by -lh_<type>_new(). These provide per-variable casts before calling the +lh_TYPE_new(). These provide per-variable casts before calling the type-specific callbacks written by the application author. These macros, as well as those used for the "doall" callbacks, are defined as; @@ -104,25 +110,25 @@ as; /* ... */ } -lh_<type>_free() frees the B<LHASH_OF(<type>> structure +lh_TYPE_free() frees the B<LHASH_OF(TYPE)> structure B<table>. Allocated hash table entries will not be freed; consider -using lh_<type>_doall() to deallocate any remaining entries in the +using lh_TYPE_doall() to deallocate any remaining entries in the hash table (see below). -lh_<type>_insert() inserts the structure pointed to by B<data> into +lh_TYPE_insert() inserts the structure pointed to by B<data> into B<table>. If there already is an entry with the same key, the old -value is replaced. Note that lh_<type>_insert() stores pointers, the +value is replaced. Note that lh_TYPE_insert() stores pointers, the data are not copied. -lh_<type>_delete() deletes an entry from B<table>. +lh_TYPE_delete() deletes an entry from B<table>. -lh_<type>_retrieve() looks up an entry in B<table>. Normally, B<data> +lh_TYPE_retrieve() looks up an entry in B<table>. Normally, B<data> is a structure with the key field(s) set; the function will return a pointer to a fully populated structure. -lh_<type>_doall() will, for every entry in the hash table, call -B<func> with the data item as its parameter. For lh_<type>_doall() -and lh_<type>_doall_arg(), function pointer casting should be avoided +lh_TYPE_doall() will, for every entry in the hash table, call +B<func> with the data item as its parameter. For lh_TYPE_doall() +and lh_TYPE_doall_arg(), function pointer casting should be avoided in the callbacks (see B<NOTE>) - instead use the declare/implement macros to create type-checked wrappers that cast variables prior to calling your type-specific callbacks. An example of this is @@ -149,7 +155,7 @@ you start (which will stop the hash table ever decreasing in size). The best solution is probably to avoid deleting items from the hash table inside a "doall" callback! -lh_<type>_doall_arg() is the same as lh_<type>_doall() except that +lh_TYPE_doall_arg() is the same as lh_TYPE_doall() except that B<func> will be called with B<arg> as the second argument and B<func> should be of type B<LHASH_DOALL_ARG_FN_TYPE> (a callback prototype that is passed both the table entry and an extra argument). As with @@ -169,27 +175,28 @@ that is provided by the caller): lh_STUFF_doall_arg(hashtable, LHASH_DOALL_ARG_FN(STUFF_print), BIO, logging_bio); -lh_<type>_error() can be used to determine if an error occurred in the last -operation. lh_<type>_error() is a macro. + +lh_TYPE_error() can be used to determine if an error occurred in the last +operation. =head1 RETURN VALUES -lh_<type>_new() returns B<NULL> on error, otherwise a pointer to the new +lh_TYPE_new() returns B<NULL> on error, otherwise a pointer to the new B<LHASH> structure. -When a hash table entry is replaced, lh_<type>_insert() returns the value +When a hash table entry is replaced, lh_TYPE_insert() returns the value being replaced. B<NULL> is returned on normal operation and on error. -lh_<type>_delete() returns the entry being deleted. B<NULL> is returned if +lh_TYPE_delete() returns the entry being deleted. B<NULL> is returned if there is no such value in the hash table. -lh_<type>_retrieve() returns the hash table entry if it has been found, +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 +lh_TYPE_error() returns 1 if an error occurred in the last operation, 0 otherwise. -lh_<type>_free(), lh_<type>_doall() and lh_<type>_doall_arg() return no values. +lh_TYPE_free(), lh_TYPE_doall() and lh_TYPE_doall_arg() return no values. =head1 NOTE @@ -232,17 +239,12 @@ without any "const" qualifiers. =head1 BUGS -lh_<type>_insert() returns B<NULL> both for success and error. +lh_TYPE_insert() returns B<NULL> both for success and error. =head1 SEE ALSO L<lh_stats(3)> -=head1 HISTORY - -In OpenSSL 1.0.0, the lhash interface was revamped for better -type checking. - =cut =head1 COPYRIGHT |