Merge branch 'vendor/LIBPCAP' (early part)
[dragonfly.git] / secure / lib / libcrypto / man / lhash.3
CommitLineData
e257b235 1.\" Automatically generated by Pod::Man 2.16 (Pod::Simple 3.05)
8b0cefbb
JR
2.\"
3.\" Standard preamble:
4.\" ========================================================================
5.de Sh \" Subsection heading
984263bc
MD
6.br
7.if t .Sp
8.ne 5
9.PP
10\fB\\$1\fR
11.PP
12..
8b0cefbb 13.de Sp \" Vertical space (when we can't use .PP)
984263bc
MD
14.if t .sp .5v
15.if n .sp
16..
8b0cefbb 17.de Vb \" Begin verbatim text
984263bc
MD
18.ft CW
19.nf
20.ne \\$1
21..
8b0cefbb 22.de Ve \" End verbatim text
984263bc 23.ft R
984263bc
MD
24.fi
25..
8b0cefbb
JR
26.\" Set up some character translations and predefined strings. \*(-- will
27.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
e257b235
PA
28.\" double quote, and \*(R" will give a right double quote. \*(C+ will
29.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
30.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
31.\" nothing in troff, for use with C<>.
32.tr \(*W-
8b0cefbb 33.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
984263bc 34.ie n \{\
8b0cefbb
JR
35. ds -- \(*W-
36. ds PI pi
37. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
38. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
39. ds L" ""
40. ds R" ""
41. ds C` ""
42. ds C' ""
984263bc
MD
43'br\}
44.el\{\
8b0cefbb
JR
45. ds -- \|\(em\|
46. ds PI \(*p
47. ds L" ``
48. ds R" ''
984263bc 49'br\}
8b0cefbb 50.\"
e257b235
PA
51.\" Escape single quotes in literal strings from groff's Unicode transform.
52.ie \n(.g .ds Aq \(aq
53.el .ds Aq '
54.\"
8b0cefbb
JR
55.\" If the F register is turned on, we'll generate index entries on stderr for
56.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
57.\" entries marked with X<> in POD. Of course, you'll have to process the
58.\" output yourself in some meaningful fashion.
e257b235 59.ie \nF \{\
8b0cefbb
JR
60. de IX
61. tm Index:\\$1\t\\n%\t"\\$2"
984263bc 62..
8b0cefbb
JR
63. nr % 0
64. rr F
984263bc 65.\}
e257b235
PA
66.el \{\
67. de IX
68..
69.\}
aac4ff6f 70.\"
8b0cefbb
JR
71.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
72.\" Fear. Run. Save yourself. No user-serviceable parts.
73. \" fudge factors for nroff and troff
984263bc 74.if n \{\
8b0cefbb
JR
75. ds #H 0
76. ds #V .8m
77. ds #F .3m
78. ds #[ \f1
79. ds #] \fP
984263bc
MD
80.\}
81.if t \{\
8b0cefbb
JR
82. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
83. ds #V .6m
84. ds #F 0
85. ds #[ \&
86. ds #] \&
984263bc 87.\}
8b0cefbb 88. \" simple accents for nroff and troff
984263bc 89.if n \{\
8b0cefbb
JR
90. ds ' \&
91. ds ` \&
92. ds ^ \&
93. ds , \&
94. ds ~ ~
95. ds /
984263bc
MD
96.\}
97.if t \{\
8b0cefbb
JR
98. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
99. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
100. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
101. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
102. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
103. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
984263bc 104.\}
8b0cefbb 105. \" troff and (daisy-wheel) nroff accents
984263bc
MD
106.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
107.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
108.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
109.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
110.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
111.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
112.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
113.ds ae a\h'-(\w'a'u*4/10)'e
114.ds Ae A\h'-(\w'A'u*4/10)'E
8b0cefbb 115. \" corrections for vroff
984263bc
MD
116.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
117.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
8b0cefbb 118. \" for low resolution devices (crt and lpr)
984263bc
MD
119.if \n(.H>23 .if \n(.V>19 \
120\{\
8b0cefbb
JR
121. ds : e
122. ds 8 ss
123. ds o a
124. ds d- d\h'-1'\(ga
125. ds D- D\h'-1'\(hy
126. ds th \o'bp'
127. ds Th \o'LP'
128. ds ae ae
129. ds Ae AE
984263bc
MD
130.\}
131.rm #[ #] #H #V #F C
8b0cefbb
JR
132.\" ========================================================================
133.\"
134.IX Title "lhash 3"
405d0527 135.TH lhash 3 "2009-04-11" "0.9.8k" "OpenSSL"
e257b235
PA
136.\" For nroff, turn off justification. Always turn off hyphenation; it makes
137.\" way too many mistakes in technical documents.
138.if n .ad l
139.nh
984263bc
MD
140.SH "NAME"
141lh_new, lh_free, lh_insert, lh_delete, lh_retrieve, lh_doall, lh_doall_arg, lh_error \- dynamic hash table
142.SH "SYNOPSIS"
8b0cefbb 143.IX Header "SYNOPSIS"
984263bc
MD
144.Vb 1
145\& #include <openssl/lhash.h>
e257b235 146\&
984263bc
MD
147\& LHASH *lh_new(LHASH_HASH_FN_TYPE hash, LHASH_COMP_FN_TYPE compare);
148\& void lh_free(LHASH *table);
e257b235 149\&
984263bc
MD
150\& void *lh_insert(LHASH *table, void *data);
151\& void *lh_delete(LHASH *table, void *data);
152\& void *lh_retrieve(LHASH *table, void *data);
e257b235 153\&
984263bc
MD
154\& void lh_doall(LHASH *table, LHASH_DOALL_FN_TYPE func);
155\& void lh_doall_arg(LHASH *table, LHASH_DOALL_ARG_FN_TYPE func,
156\& void *arg);
e257b235 157\&
984263bc 158\& int lh_error(LHASH *table);
e257b235 159\&
984263bc
MD
160\& typedef int (*LHASH_COMP_FN_TYPE)(const void *, const void *);
161\& typedef unsigned long (*LHASH_HASH_FN_TYPE)(const void *);
162\& typedef void (*LHASH_DOALL_FN_TYPE)(const void *);
163\& typedef void (*LHASH_DOALL_ARG_FN_TYPE)(const void *, const void *);
164.Ve
165.SH "DESCRIPTION"
8b0cefbb 166.IX Header "DESCRIPTION"
984263bc
MD
167This library implements dynamic hash tables. The hash table entries
168can be arbitrary structures. Usually they consist of key and value
169fields.
170.PP
8b0cefbb
JR
171\&\fIlh_new()\fR creates a new \fB\s-1LHASH\s0\fR structure to store arbitrary data
172entries, and provides the 'hash' and 'compare' callbacks to be used in
984263bc
MD
173organising the table's entries. The \fBhash\fR callback takes a pointer
174to a table entry as its argument and returns an unsigned long hash
175value for its key field. The hash value is normally truncated to a
176power of 2, so make sure that your hash function returns well mixed
177low order bits. The \fBcompare\fR callback takes two arguments (pointers
178to two hash table entries), and returns 0 if their keys are equal,
179non-zero otherwise. If your hash table will contain items of some
180particular type and the \fBhash\fR and \fBcompare\fR callbacks hash/compare
8b0cefbb
JR
181these types, then the \fB\s-1DECLARE_LHASH_HASH_FN\s0\fR and
182\&\fB\s-1IMPLEMENT_LHASH_COMP_FN\s0\fR macros can be used to create callback
984263bc
MD
183wrappers of the prototypes required by \fIlh_new()\fR. These provide
184per-variable casts before calling the type-specific callbacks written
185by the application author. These macros, as well as those used for
186the \*(L"doall\*(R" callbacks, are defined as;
187.PP
188.Vb 7
189\& #define DECLARE_LHASH_HASH_FN(f_name,o_type) \e
190\& unsigned long f_name##_LHASH_HASH(const void *);
191\& #define IMPLEMENT_LHASH_HASH_FN(f_name,o_type) \e
192\& unsigned long f_name##_LHASH_HASH(const void *arg) { \e
193\& o_type a = (o_type)arg; \e
194\& return f_name(a); }
195\& #define LHASH_HASH_FN(f_name) f_name##_LHASH_HASH
e257b235 196\&
984263bc
MD
197\& #define DECLARE_LHASH_COMP_FN(f_name,o_type) \e
198\& int f_name##_LHASH_COMP(const void *, const void *);
199\& #define IMPLEMENT_LHASH_COMP_FN(f_name,o_type) \e
200\& int f_name##_LHASH_COMP(const void *arg1, const void *arg2) { \e
201\& o_type a = (o_type)arg1; \e
202\& o_type b = (o_type)arg2; \e
203\& return f_name(a,b); }
204\& #define LHASH_COMP_FN(f_name) f_name##_LHASH_COMP
e257b235 205\&
984263bc
MD
206\& #define DECLARE_LHASH_DOALL_FN(f_name,o_type) \e
207\& void f_name##_LHASH_DOALL(const void *);
208\& #define IMPLEMENT_LHASH_DOALL_FN(f_name,o_type) \e
209\& void f_name##_LHASH_DOALL(const void *arg) { \e
210\& o_type a = (o_type)arg; \e
211\& f_name(a); }
212\& #define LHASH_DOALL_FN(f_name) f_name##_LHASH_DOALL
e257b235 213\&
984263bc
MD
214\& #define DECLARE_LHASH_DOALL_ARG_FN(f_name,o_type,a_type) \e
215\& void f_name##_LHASH_DOALL_ARG(const void *, const void *);
216\& #define IMPLEMENT_LHASH_DOALL_ARG_FN(f_name,o_type,a_type) \e
217\& void f_name##_LHASH_DOALL_ARG(const void *arg1, const void *arg2) { \e
218\& o_type a = (o_type)arg1; \e
219\& a_type b = (a_type)arg2; \e
220\& f_name(a,b); }
221\& #define LHASH_DOALL_ARG_FN(f_name) f_name##_LHASH_DOALL_ARG
222.Ve
8b0cefbb
JR
223.PP
224An example of a hash table storing (pointers to) structures of type '\s-1STUFF\s0'
984263bc
MD
225could be defined as follows;
226.PP
e257b235
PA
227.Vb 10
228\& /* Calculates the hash value of \*(Aqtohash\*(Aq (implemented elsewhere) */
984263bc 229\& unsigned long STUFF_hash(const STUFF *tohash);
e257b235 230\& /* Orders \*(Aqarg1\*(Aq and \*(Aqarg2\*(Aq (implemented elsewhere) */
984263bc 231\& int STUFF_cmp(const STUFF *arg1, const STUFF *arg2);
e257b235 232\& /* Create the type\-safe wrapper functions for use in the LHASH internals */
984263bc
MD
233\& static IMPLEMENT_LHASH_HASH_FN(STUFF_hash, const STUFF *)
234\& static IMPLEMENT_LHASH_COMP_FN(STUFF_cmp, const STUFF *);
235\& /* ... */
236\& int main(int argc, char *argv[]) {
237\& /* Create the new hash table using the hash/compare wrappers */
238\& LHASH *hashtable = lh_new(LHASH_HASH_FN(STUFF_hash),
239\& LHASH_COMP_FN(STUFF_cmp));
240\& /* ... */
241\& }
242.Ve
8b0cefbb
JR
243.PP
244\&\fIlh_free()\fR frees the \fB\s-1LHASH\s0\fR structure \fBtable\fR. Allocated hash table
984263bc
MD
245entries will not be freed; consider using \fIlh_doall()\fR to deallocate any
246remaining entries in the hash table (see below).
247.PP
8b0cefbb 248\&\fIlh_insert()\fR inserts the structure pointed to by \fBdata\fR into \fBtable\fR.
984263bc
MD
249If there already is an entry with the same key, the old value is
250replaced. Note that \fIlh_insert()\fR stores pointers, the data are not
251copied.
252.PP
8b0cefbb 253\&\fIlh_delete()\fR deletes an entry from \fBtable\fR.
984263bc 254.PP
8b0cefbb
JR
255\&\fIlh_retrieve()\fR looks up an entry in \fBtable\fR. Normally, \fBdata\fR is
256a structure with the key field(s) set; the function will return a
984263bc
MD
257pointer to a fully populated structure.
258.PP
8b0cefbb 259\&\fIlh_doall()\fR will, for every entry in the hash table, call \fBfunc\fR with
984263bc
MD
260the data item as its parameter. For \fIlh_doall()\fR and \fIlh_doall_arg()\fR,
261function pointer casting should be avoided in the callbacks (see
8b0cefbb 262\&\fB\s-1NOTE\s0\fR) \- instead, either declare the callbacks to match the
984263bc
MD
263prototype required in \fIlh_new()\fR or use the declare/implement macros to
264create type-safe wrappers that cast variables prior to calling your
265type-specific callbacks. An example of this is illustrated here where
266the callback is used to cleanup resources for items in the hash table
267prior to the hashtable itself being deallocated:
268.PP
269.Vb 9
e257b235 270\& /* Cleans up resources belonging to \*(Aqa\*(Aq (this is implemented elsewhere) */
984263bc 271\& void STUFF_cleanup(STUFF *a);
e257b235 272\& /* Implement a prototype\-compatible wrapper for "STUFF_cleanup" */
984263bc
MD
273\& IMPLEMENT_LHASH_DOALL_FN(STUFF_cleanup, STUFF *)
274\& /* ... then later in the code ... */
275\& /* So to run "STUFF_cleanup" against all items in a hash table ... */
276\& lh_doall(hashtable, LHASH_DOALL_FN(STUFF_cleanup));
277\& /* Then the hash table itself can be deallocated */
278\& lh_free(hashtable);
279.Ve
8b0cefbb 280.PP
984263bc
MD
281When doing this, be careful if you delete entries from the hash table
282in your callbacks: the table may decrease in size, moving the item
283that you are currently on down lower in the hash table \- this could
284cause some entries to be skipped during the iteration. The second
8b0cefbb 285best solution to this problem is to set hash\->down_load=0 before
984263bc
MD
286you start (which will stop the hash table ever decreasing in size).
287The best solution is probably to avoid deleting items from the hash
288table inside a \*(L"doall\*(R" callback!
289.PP
8b0cefbb 290\&\fIlh_doall_arg()\fR is the same as \fIlh_doall()\fR except that \fBfunc\fR will be
984263bc 291called with \fBarg\fR as the second argument and \fBfunc\fR should be of
8b0cefbb 292type \fB\s-1LHASH_DOALL_ARG_FN_TYPE\s0\fR (a callback prototype that is passed
984263bc
MD
293both the table entry and an extra argument). As with \fIlh_doall()\fR, you
294can instead choose to declare your callback with a prototype matching
295the types you are dealing with and use the declare/implement macros to
296create compatible wrappers that cast variables before calling your
297type-specific callbacks. An example of this is demonstrated here
8b0cefbb 298(printing all hash table entries to a \s-1BIO\s0 that is provided by the
984263bc
MD
299caller):
300.PP
8b0cefbb 301.Vb 7
e257b235 302\& /* Prints item \*(Aqa\*(Aq to \*(Aqoutput_bio\*(Aq (this is implemented elsewhere) */
984263bc 303\& void STUFF_print(const STUFF *a, BIO *output_bio);
e257b235 304\& /* Implement a prototype\-compatible wrapper for "STUFF_print" */
984263bc
MD
305\& static IMPLEMENT_LHASH_DOALL_ARG_FN(STUFF_print, const STUFF *, BIO *)
306\& /* ... then later in the code ... */
307\& /* Print out the entire hashtable to a particular BIO */
308\& lh_doall_arg(hashtable, LHASH_DOALL_ARG_FN(STUFF_print), logging_bio);
309.Ve
8b0cefbb
JR
310.PP
311\&\fIlh_error()\fR can be used to determine if an error occurred in the last
312operation. \fIlh_error()\fR is a macro.
984263bc 313.SH "RETURN VALUES"
8b0cefbb
JR
314.IX Header "RETURN VALUES"
315\&\fIlh_new()\fR returns \fB\s-1NULL\s0\fR on error, otherwise a pointer to the new
316\&\fB\s-1LHASH\s0\fR structure.
984263bc
MD
317.PP
318When a hash table entry is replaced, \fIlh_insert()\fR returns the value
8b0cefbb 319being replaced. \fB\s-1NULL\s0\fR is returned on normal operation and on error.
984263bc 320.PP
8b0cefbb 321\&\fIlh_delete()\fR returns the entry being deleted. \fB\s-1NULL\s0\fR is returned if
984263bc
MD
322there is no such value in the hash table.
323.PP
8b0cefbb
JR
324\&\fIlh_retrieve()\fR returns the hash table entry if it has been found,
325\&\fB\s-1NULL\s0\fR otherwise.
984263bc 326.PP
8b0cefbb 327\&\fIlh_error()\fR returns 1 if an error occurred in the last operation, 0
984263bc
MD
328otherwise.
329.PP
8b0cefbb 330\&\fIlh_free()\fR, \fIlh_doall()\fR and \fIlh_doall_arg()\fR return no values.
984263bc 331.SH "NOTE"
8b0cefbb
JR
332.IX Header "NOTE"
333The various \s-1LHASH\s0 macros and callback types exist to make it possible
984263bc
MD
334to write type-safe code without resorting to function-prototype
335casting \- an evil that makes application code much harder to
336audit/verify and also opens the window of opportunity for stack
337corruption and other hard-to-find bugs. It also, apparently, violates
e257b235 338ANSI-C.
984263bc 339.PP
8b0cefbb 340The \s-1LHASH\s0 code regards table entries as constant data. As such, it
984263bc
MD
341internally represents \fIlh_insert()\fR'd items with a \*(L"const void *\*(R"
342pointer type. This is why callbacks such as those used by \fIlh_doall()\fR
343and \fIlh_doall_arg()\fR declare their prototypes with \*(L"const\*(R", even for the
8b0cefbb 344parameters that pass back the table items' data pointers \- for
984263bc 345consistency, user-provided data is \*(L"const\*(R" at all times as far as the
8b0cefbb 346\&\s-1LHASH\s0 code is concerned. However, as callers are themselves providing
984263bc
MD
347these pointers, they can choose whether they too should be treating
348all such parameters as constant.
349.PP
350As an example, a hash table may be maintained by code that, for
351reasons of encapsulation, has only \*(L"const\*(R" access to the data being
352indexed in the hash table (ie. it is returned as \*(L"const\*(R" from
8b0cefbb 353elsewhere in their code) \- in this case the \s-1LHASH\s0 prototypes are
e257b235 354appropriate as-is. Conversely, if the caller is responsible for the
984263bc
MD
355life-time of the data in question, then they may well wish to make
356modifications to table item passed back in the \fIlh_doall()\fR or
8b0cefbb 357\&\fIlh_doall_arg()\fR callbacks (see the \*(L"STUFF_cleanup\*(R" example above). If
984263bc
MD
358so, the caller can either cast the \*(L"const\*(R" away (if they're providing
359the raw callbacks themselves) or use the macros to declare/implement
360the wrapper functions without \*(L"const\*(R" types.
361.PP
362Callers that only have \*(L"const\*(R" access to data they're indexing in a
363table, yet declare callbacks without constant types (or cast the
8b0cefbb
JR
364\&\*(L"const\*(R" away themselves), are therefore creating their own risks/bugs
365without being encouraged to do so by the \s-1API\s0. On a related note,
984263bc 366those auditing code should pay special attention to any instances of
8b0cefbb 367DECLARE/IMPLEMENT_LHASH_DOALL_[\s-1ARG_\s0]_FN macros that provide types
984263bc
MD
368without any \*(L"const\*(R" qualifiers.
369.SH "BUGS"
8b0cefbb
JR
370.IX Header "BUGS"
371\&\fIlh_insert()\fR returns \fB\s-1NULL\s0\fR both for success and error.
984263bc 372.SH "INTERNALS"
8b0cefbb 373.IX Header "INTERNALS"
984263bc
MD
374The following description is based on the SSLeay documentation:
375.PP
376The \fBlhash\fR library implements a hash table described in the
8b0cefbb 377\&\fICommunications of the \s-1ACM\s0\fR in 1991. What makes this hash table
984263bc 378different is that as the table fills, the hash table is increased (or
8b0cefbb
JR
379decreased) in size via \fIOPENSSL_realloc()\fR. When a 'resize' is done, instead of
380all hashes being redistributed over twice as many 'buckets', one
381bucket is split. So when an 'expand' is done, there is only a minimal
984263bc 382cost to redistribute some values. Subsequent inserts will cause more
8b0cefbb
JR
383single 'bucket' redistributions but there will never be a sudden large
384cost due to redistributing all the 'buckets'.
984263bc 385.PP
8b0cefbb 386The state for a particular hash table is kept in the \fB\s-1LHASH\s0\fR structure.
984263bc 387The decision to increase or decrease the hash table size is made
8b0cefbb 388depending on the 'load' of the hash table. The load is the number of
984263bc 389items in the hash table divided by the size of the hash table. The
8b0cefbb
JR
390default values are as follows. If (hash\->up_load < load) =>
391expand. if (hash\->down_load > load) => contract. The
392\&\fBup_load\fR has a default value of 1 and \fBdown_load\fR has a default value
984263bc 393of 2. These numbers can be modified by the application by just
8b0cefbb 394playing with the \fBup_load\fR and \fBdown_load\fR variables. The 'load' is
984263bc 395kept in a form which is multiplied by 256. So
8b0cefbb 396hash\->up_load=8*256; will cause a load of 8 to be set.
984263bc
MD
397.PP
398If you are interested in performance the field to watch is
8b0cefbb
JR
399num_comp_calls. The hash library keeps track of the 'hash' value for
400each item so when a lookup is done, the 'hashes' are compared, if
984263bc 401there is a match, then a full compare is done, and
8b0cefbb 402hash\->num_comp_calls is incremented. If num_comp_calls is not equal
984263bc
MD
403to num_delete plus num_retrieve it means that your hash function is
404generating hashes that are the same for different values. It is
405probably worth changing your hash function if this is the case because
8b0cefbb 406even if your hash table has 10 items in a 'bucket', it can be searched
984263bc
MD
407with 10 \fBunsigned long\fR compares and 10 linked list traverses. This
408will be much less expensive that 10 calls to your compare function.
409.PP
8b0cefbb 410\&\fIlh_strhash()\fR is a demo string hashing function:
984263bc
MD
411.PP
412.Vb 1
413\& unsigned long lh_strhash(const char *c);
414.Ve
8b0cefbb
JR
415.PP
416Since the \fB\s-1LHASH\s0\fR routines would normally be passed structures, this
984263bc
MD
417routine would not normally be passed to \fIlh_new()\fR, rather it would be
418used in the function passed to \fIlh_new()\fR.
419.SH "SEE ALSO"
8b0cefbb
JR
420.IX Header "SEE ALSO"
421\&\fIlh_stats\fR\|(3)
984263bc 422.SH "HISTORY"
8b0cefbb 423.IX Header "HISTORY"
984263bc 424The \fBlhash\fR library is available in all versions of SSLeay and OpenSSL.
8b0cefbb 425\&\fIlh_error()\fR was added in SSLeay 0.9.1b.
984263bc
MD
426.PP
427This manpage is derived from the SSLeay documentation.
428.PP
429In OpenSSL 0.9.7, all lhash functions that were passed function pointers
8b0cefbb
JR
430were changed for better type safety, and the function types \s-1LHASH_COMP_FN_TYPE\s0,
431\&\s-1LHASH_HASH_FN_TYPE\s0, \s-1LHASH_DOALL_FN_TYPE\s0 and \s-1LHASH_DOALL_ARG_FN_TYPE\s0
984263bc 432became available.