Standard preamble:
========================================================================
..
.... Set up some character translations and predefined strings. \*(-- will
give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
double quote, and \*(R" will give a right double quote. \*(C+ will
give a nicer C++. Capital omega is used to do unbreakable dashes and
therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
nothing in troff, for use with C<>.
.tr \(*W- . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\}
Escape single quotes in literal strings from groff's Unicode transform.
If the F register is >0, we'll generate index entries on stderr for
titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
entries marked with X<> in POD. Of course, you'll have to process the
output yourself in some meaningful fashion.
Avoid warning from groff about undefined register 'F'.
.. .nr rF 0 . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] .\} . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents . \" corrections for vroff . \" for low resolution devices (crt and lpr) \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} ========================================================================
Title "OPENSSL_LH_COMPFUNC 3ossl"
way too many mistakes in technical documents.
\fBlh_\f(BI\s-1TYPE\s0_new() creates a new \s-1LHASH_OF\s0(\f(BI\s-1TYPE\s0) structure to store arbitrary data entries, and specifies the 'hash' and 'compare' callbacks to be used in organising the table's entries. The hash callback takes a pointer to a table entry as its argument and returns an unsigned long hash value for its key field. The hash value is normally truncated to a power of 2, so make sure that your hash function returns well mixed low order bits. The compare callback takes two arguments (pointers to two hash table entries), and returns 0 if their keys are equal, nonzero otherwise.
If your hash table will contain items of some particular type and the hash and \fIcompare callbacks hash/compare these types, then the \fB\s-1IMPLEMENT_LHASH_HASH_FN\s0 and \s-1IMPLEMENT_LHASH_COMP_FN\s0 macros can be used to create callback wrappers of the prototypes required by \fBlh_\f(BI\s-1TYPE\s0_new() as shown in this example:
.Vb 11 /* * Implement the hash and compare functions; "stuff" can be any word. */ static unsigned long stuff_hash(const TYPE *a) { ... } static int stuff_cmp(const TYPE *a, const TYPE *b) { ... } \& /* * Implement the wrapper functions. */ static IMPLEMENT_LHASH_HASH_FN(stuff, TYPE) static IMPLEMENT_LHASH_COMP_FN(stuff, TYPE) .Ve
If the type is going to be used in several places, the following macros can be used in a common header file to declare the function wrappers:
.Vb 2 DECLARE_LHASH_HASH_FN(stuff, TYPE) DECLARE_LHASH_COMP_FN(stuff, TYPE) .Ve
Then a hash table of \f(BI\s-1TYPE\s0 objects can be created using this:
.Vb 1 LHASH_OF(TYPE) *htable; \& htable = B<lh_I<TYPE>_new>(LHASH_HASH_FN(stuff), LHASH_COMP_FN(stuff)); .Ve
\fBlh_\f(BI\s-1TYPE\s0_free() frees the \s-1LHASH_OF\s0(\f(BI\s-1TYPE\s0) structure \fItable. Allocated hash table entries will not be freed; consider using lh_\f(BI\s-1TYPE\s0_doall() to deallocate any remaining entries in the hash table (see below).
\fBlh_\f(BI\s-1TYPE\s0_flush() empties the \s-1LHASH_OF\s0(\f(BI\s-1TYPE\s0) structure table. New entries can be added to the flushed table. Allocated hash table entries will not be freed; consider using lh_\f(BI\s-1TYPE\s0_doall() to deallocate any remaining entries in the hash table (see below).
\fBlh_\f(BI\s-1TYPE\s0_insert() inserts the structure pointed to by data into \fItable. If there already is an entry with the same key, the old value is replaced. Note that lh_\f(BI\s-1TYPE\s0_insert() stores pointers, the data are not copied.
\fBlh_\f(BI\s-1TYPE\s0_delete() deletes an entry from table.
\fBlh_\f(BI\s-1TYPE\s0_retrieve() looks up an entry in table. Normally, data is a structure with the key field(s) set; the function will return a pointer to a fully populated structure.
\fBlh_\f(BI\s-1TYPE\s0_doall() will, for every entry in the hash table, call \fIfunc with the data item as its parameter. For example:
.Vb 2 /* Cleans up resources belonging to \*(Aqa\*(Aq (this is implemented elsewhere) */ void TYPE_cleanup_doall(TYPE *a); \& /* Implement a prototype-compatible wrapper for "TYPE_cleanup" */ IMPLEMENT_LHASH_DOALL_FN(TYPE_cleanup, TYPE) \& /* Call "TYPE_cleanup" against all items in a hash table. */ lh_TYPE_doall(hashtable, LHASH_DOALL_FN(TYPE_cleanup)); \& /* Then the hash table itself can be deallocated */ lh_TYPE_free(hashtable); .Ve
When doing this, be careful if you delete entries from the hash table in your callbacks: the table may decrease in size, moving the item that you are currently on down lower in the hash table - this could cause some entries to be skipped during the iteration. The second best solution to this problem is to set hash->down_load=0 before 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 \*(L"doall\*(R" callback!
\fBlh_\f(BI\s-1TYPE\s0_doall_arg() is the same as lh_\f(BI\s-1TYPE\s0_doall() except that \fIfunc will be called with arg as the second argument and func should be of type \s-1LHASH_DOALL_ARG_FN\s0(\f(BI\s-1TYPE\s0) (a callback prototype that is passed both the table entry and an extra argument). As with \fBlh_doall(), you can instead choose to declare your callback with a prototype matching the types you are dealing with and use the declare/implement macros to create compatible wrappers that cast variables before calling your type-specific callbacks. An example of this is demonstrated here (printing all hash table entries to a \s-1BIO\s0 that is provided by the caller):
.Vb 2 /* Prints item \*(Aqa\*(Aq to \*(Aqoutput_bio\*(Aq (this is implemented elsewhere) */ void TYPE_print_doall_arg(const TYPE *a, BIO *output_bio); \& /* Implement a prototype-compatible wrapper for "TYPE_print" */ static IMPLEMENT_LHASH_DOALL_ARG_FN(TYPE, const TYPE, BIO) \& /* Print out the entire hashtable to a particular BIO */ lh_TYPE_doall_arg(hashtable, LHASH_DOALL_ARG_FN(TYPE_print), BIO, logging_bio); .Ve
\fBlh_\f(BI\s-1TYPE\s0_error() can be used to determine if an error occurred in the last operation.
\fBOPENSSL_LH_new() is the same as the lh_\f(BI\s-1TYPE\s0_new() except that it is not type specific. So instead of returning an \s-1LHASH_OF\s0(\f(BI\s-1TYPE\s0) value it returns a void *. In the same way the functions OPENSSL_LH_free(), \fBOPENSSL_LH_flush(), OPENSSL_LH_insert(), OPENSSL_LH_delete(), \fBOPENSSL_LH_retrieve(), OPENSSL_LH_doall(), OPENSSL_LH_doall_arg(), and \fBOPENSSL_LH_error() are equivalent to the similarly named lh_\f(BI\s-1TYPE\s0 functions except that they return or use a void * where the equivalent lh_\f(BI\s-1TYPE\s0 function returns or uses a \f(BI\s-1TYPE\s0 * or \s-1LHASH_OF\s0(\f(BI\s-1TYPE\s0) *. lh_\f(BI\s-1TYPE\s0 functions are implemented as type checked wrappers around the \s-1OPENSSL_LH\s0 functions. Most applications should not call the \s-1OPENSSL_LH\s0 functions directly.
When a hash table entry is replaced, lh_\f(BI\s-1TYPE\s0_insert() or \fBOPENSSL_LH_insert() return the value being replaced. \s-1NULL\s0 is returned on normal operation and on error.
\fBlh_\f(BI\s-1TYPE\s0_delete() and OPENSSL_LH_delete() return the entry being deleted. \s-1NULL\s0 is returned if there is no such value in the hash table.
\fBlh_\f(BI\s-1TYPE\s0_retrieve() and OPENSSL_LH_retrieve() return the hash table entry if it has been found, \s-1NULL\s0 otherwise.
\fBlh_\f(BI\s-1TYPE\s0_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.
\fBlh_\f(BI\s-1TYPE\s0_free(), OPENSSL_LH_free(), lh_\f(BI\s-1TYPE\s0_flush(), \fBOPENSSL_LH_flush(), lh_\f(BI\s-1TYPE\s0_doall() OPENSSL_LH_doall(), \fBlh_\f(BI\s-1TYPE\s0_doall_arg() and OPENSSL_LH_doall_arg() return no values.
The \s-1LHASH\s0 code regards table entries as constant data. As such, it internally represents lh_insert()'d items with a \*(L"const void *\*(R" pointer type. This is why callbacks such as those used by lh_doall() and lh_doall_arg() declare their prototypes with \*(L"const\*(R", even for the parameters that pass back the table items' data pointers - for consistency, user-provided data is \*(L"const\*(R" at all times as far as the \s-1LHASH\s0 code is concerned. However, as callers are themselves providing these pointers, they can choose whether they too should be treating all such parameters as constant.
As an example, a hash table may be maintained by code that, for reasons of encapsulation, has only \*(L"const\*(R" access to the data being indexed in the hash table (i.e. it is returned as \*(L"const\*(R" from elsewhere in their code) - in this case the \s-1LHASH\s0 prototypes are appropriate as-is. Conversely, if the caller is responsible for the life-time of the data in question, then they may well wish to make modifications to table item passed back in the lh_doall() or \fBlh_doall_arg() callbacks (see the \*(L"TYPE_cleanup\*(R" example above). If so, the caller can either cast the \*(L"const\*(R" away (if they're providing the raw callbacks themselves) or use the macros to declare/implement the wrapper functions without \*(L"const\*(R" types.
Callers that only have \*(L"const\*(R" access to data they're indexing in a table, yet declare callbacks without constant types (or cast the \*(L"const\*(R" away themselves), are therefore creating their own risks/bugs without being encouraged to do so by the \s-1API.\s0 On a related note, those auditing code should pay special attention to any instances of DECLARE/IMPLEMENT_LHASH_DOALL_[\s-1ARG_\s0]_FN macros that provide types without any \*(L"const\*(R" qualifiers.
Licensed under the Apache License 2.0 (the \*(L"License\*(R"). You may not use this file except in compliance with the License. You can obtain a copy in the file \s-1LICENSE\s0 in the source distribution or at <https://www.openssl.org/source/license.html>.