=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
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;
#define DECLARE_LHASH_HASH_FN(name, o_type) \
- unsigned long name##_LHASH_HASH(const void *);
+ unsigned long name##_LHASH_HASH(const void *);
#define IMPLEMENT_LHASH_HASH_FN(name, o_type) \
- unsigned long name##_LHASH_HASH(const void *arg) { \
- const o_type *a = arg; \
- return name##_hash(a); }
+ unsigned long name##_LHASH_HASH(const void *arg) { \
+ const o_type *a = arg; \
+ return name##_hash(a); }
#define LHASH_HASH_FN(name) name##_LHASH_HASH
#define DECLARE_LHASH_COMP_FN(name, o_type) \
- int name##_LHASH_COMP(const void *, const void *);
+ int name##_LHASH_COMP(const void *, const void *);
#define IMPLEMENT_LHASH_COMP_FN(name, o_type) \
- int name##_LHASH_COMP(const void *arg1, const void *arg2) { \
- const o_type *a = arg1; \
- const o_type *b = arg2; \
- return name##_cmp(a,b); }
+ int name##_LHASH_COMP(const void *arg1, const void *arg2) { \
+ const o_type *a = arg1; \
+ const o_type *b = arg2; \
+ return name##_cmp(a,b); }
#define LHASH_COMP_FN(name) name##_LHASH_COMP
#define DECLARE_LHASH_DOALL_FN(name, o_type) \
- void name##_LHASH_DOALL(void *);
+ void name##_LHASH_DOALL(void *);
#define IMPLEMENT_LHASH_DOALL_FN(name, o_type) \
- void name##_LHASH_DOALL(void *arg) { \
- o_type *a = arg; \
- name##_doall(a); }
+ void name##_LHASH_DOALL(void *arg) { \
+ o_type *a = arg; \
+ name##_doall(a); }
#define LHASH_DOALL_FN(name) name##_LHASH_DOALL
#define DECLARE_LHASH_DOALL_ARG_FN(name, o_type, a_type) \
- void name##_LHASH_DOALL_ARG(void *, void *);
+ void name##_LHASH_DOALL_ARG(void *, void *);
#define IMPLEMENT_LHASH_DOALL_ARG_FN(name, o_type, a_type) \
- void name##_LHASH_DOALL_ARG(void *arg1, void *arg2) { \
- o_type *a = arg1; \
- a_type *b = arg2; \
- name##_doall_arg(a, b); }
+ void name##_LHASH_DOALL_ARG(void *arg1, void *arg2) { \
+ o_type *a = arg1; \
+ a_type *b = arg2; \
+ name##_doall_arg(a, b); }
#define LHASH_DOALL_ARG_FN(name) name##_LHASH_DOALL_ARG
An example of a hash table storing (pointers to) structures of type 'STUFF'
/* Create the new hash table using the hash/compare wrappers */
LHASH_OF(STUFF) *hashtable = lh_STUFF_new(LHASH_HASH_FN(STUFF_hash),
LHASH_COMP_FN(STUFF_cmp));
- /* ... */
+ /* ... */
}
-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
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
/* Print out the entire hashtable to a particular BIO */
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
=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
In OpenSSL 1.0.0, the lhash interface was revamped for better
type checking.
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
=cut
projects / openssl.git / blobdiff