diff options
Diffstat (limited to 'secure/lib/libcrypto/man/lhash.3')
| -rw-r--r-- | secure/lib/libcrypto/man/lhash.3 | 67 |
1 files changed, 35 insertions, 32 deletions
diff --git a/secure/lib/libcrypto/man/lhash.3 b/secure/lib/libcrypto/man/lhash.3 index 6c0dada..bd3b6ec 100644 --- a/secure/lib/libcrypto/man/lhash.3 +++ b/secure/lib/libcrypto/man/lhash.3 @@ -1,8 +1,7 @@ -.\" Automatically generated by Pod::Man version 1.15 -.\" Wed Mar 17 09:38:43 2004 +.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.14 .\" .\" Standard preamble: -.\" ====================================================================== +.\" ======================================================================== .de Sh \" Subsection heading .br .if t .Sp @@ -15,12 +14,6 @@ .if t .sp .5v .if n .sp .. -.de Ip \" List item -.br -.ie \\n(.$>=3 .ne \\$3 -.el .ne 3 -.IP "\\$1" \\$2 -.. .de Vb \" Begin verbatim text .ft CW .nf @@ -28,15 +21,14 @@ .. .de Ve \" End verbatim text .ft R - .fi .. .\" 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. | will give a -.\" real vertical bar. \*(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<> +.\" real vertical bar. \*(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-|\(bv\*(Tr .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ @@ -56,10 +48,10 @@ . ds R" '' 'br\} .\" -.\" If the F register is turned on, we'll generate index entries on stderr -.\" for titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and -.\" index entries marked with X<> in POD. Of course, you'll have to process -.\" the output yourself in some meaningful fashion. +.\" If the F register is turned on, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. .if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" @@ -68,14 +60,13 @@ . rr F .\} .\" -.\" For nroff, turn off justification. Always turn off hyphenation; it -.\" makes way too many mistakes in technical documents. +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. .hy 0 .if n .na .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. -.bd B 3 . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 @@ -135,11 +126,10 @@ . ds Ae AE .\} .rm #[ #] #H #V #F C -.\" ====================================================================== +.\" ======================================================================== .\" .IX Title "lhash 3" -.TH lhash 3 "0.9.7d" "2004-03-17" "OpenSSL" -.UC +.TH lhash 3 "2005-02-24" "0.9.7d" "OpenSSL" .SH "NAME" lh_new, lh_free, lh_insert, lh_delete, lh_retrieve, lh_doall, lh_doall_arg, lh_error \- dynamic hash table .SH "SYNOPSIS" @@ -147,23 +137,28 @@ lh_new, lh_free, lh_insert, lh_delete, lh_retrieve, lh_doall, lh_doall_arg, lh_e .Vb 1 \& #include <openssl/lhash.h> .Ve +.PP .Vb 2 \& LHASH *lh_new(LHASH_HASH_FN_TYPE hash, LHASH_COMP_FN_TYPE compare); \& void lh_free(LHASH *table); .Ve +.PP .Vb 3 \& void *lh_insert(LHASH *table, void *data); \& void *lh_delete(LHASH *table, void *data); \& void *lh_retrieve(LHASH *table, void *data); .Ve +.PP .Vb 3 \& void lh_doall(LHASH *table, LHASH_DOALL_FN_TYPE func); \& void lh_doall_arg(LHASH *table, LHASH_DOALL_ARG_FN_TYPE func, \& void *arg); .Ve +.PP .Vb 1 \& int lh_error(LHASH *table); .Ve +.PP .Vb 4 \& typedef int (*LHASH_COMP_FN_TYPE)(const void *, const void *); \& typedef unsigned long (*LHASH_HASH_FN_TYPE)(const void *); @@ -202,6 +197,7 @@ the \*(L"doall\*(R" callbacks, are defined as; \& return f_name(a); } \& #define LHASH_HASH_FN(f_name) f_name##_LHASH_HASH .Ve +.PP .Vb 8 \& #define DECLARE_LHASH_COMP_FN(f_name,o_type) \e \& int f_name##_LHASH_COMP(const void *, const void *); @@ -212,6 +208,7 @@ the \*(L"doall\*(R" callbacks, are defined as; \& return f_name(a,b); } \& #define LHASH_COMP_FN(f_name) f_name##_LHASH_COMP .Ve +.PP .Vb 7 \& #define DECLARE_LHASH_DOALL_FN(f_name,o_type) \e \& void f_name##_LHASH_DOALL(const void *); @@ -221,6 +218,7 @@ the \*(L"doall\*(R" callbacks, are defined as; \& f_name(a); } \& #define LHASH_DOALL_FN(f_name) f_name##_LHASH_DOALL .Ve +.PP .Vb 8 \& #define DECLARE_LHASH_DOALL_ARG_FN(f_name,o_type,a_type) \e \& void f_name##_LHASH_DOALL_ARG(const void *, const void *); @@ -231,6 +229,7 @@ the \*(L"doall\*(R" callbacks, are defined as; \& f_name(a,b); } \& #define LHASH_DOALL_ARG_FN(f_name) f_name##_LHASH_DOALL_ARG .Ve +.PP An example of a hash table storing (pointers to) structures of type '\s-1STUFF\s0' could be defined as follows; .PP @@ -250,6 +249,7 @@ could be defined as follows; \& /* ... */ \& } .Ve +.PP \&\fIlh_free()\fR frees the \fB\s-1LHASH\s0\fR structure \fBtable\fR. Allocated hash table entries will not be freed; consider using \fIlh_doall()\fR to deallocate any remaining entries in the hash table (see below). @@ -262,7 +262,7 @@ copied. \&\fIlh_delete()\fR deletes an entry from \fBtable\fR. .PP \&\fIlh_retrieve()\fR looks up an entry in \fBtable\fR. Normally, \fBdata\fR is -a structure with the key \fIfield\fR\|(s) set; the function will return a +a structure with the key field(s) set; the function will return a pointer to a fully populated structure. .PP \&\fIlh_doall()\fR will, for every entry in the hash table, call \fBfunc\fR with @@ -286,11 +286,12 @@ prior to the hashtable itself being deallocated: \& /* Then the hash table itself can be deallocated */ \& lh_free(hashtable); .Ve +.PP 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 +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! @@ -315,6 +316,7 @@ caller): \& /* Print out the entire hashtable to a particular BIO */ \& lh_doall_arg(hashtable, LHASH_DOALL_ARG_FN(STUFF_print), logging_bio); .Ve +.PP \&\fIlh_error()\fR can be used to determine if an error occurred in the last operation. \fIlh_error()\fR is a macro. .SH "RETURN VALUES" @@ -342,7 +344,7 @@ to write type-safe 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 -\&\s-1ANSI-C\s0. +\&\s-1ANSI\-C\s0. .PP The \s-1LHASH\s0 code regards table entries as constant data. As such, it internally represents \fIlh_insert()\fR'd items with a \*(L"const void *\*(R" @@ -358,7 +360,7 @@ 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 (ie. 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 +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 \fIlh_doall()\fR or \&\fIlh_doall_arg()\fR callbacks (see the \*(L"STUFF_cleanup\*(R" example above). If @@ -394,19 +396,19 @@ The state for a particular hash table is kept in the \fB\s-1LHASH\s0\fR structur The decision to increase or decrease the hash table size is made depending on the 'load' of the hash table. The load is the number of items in the hash table divided by the size of the hash table. The -default values are as follows. If (hash->up_load < load) => -expand. if (hash->down_load > load) => contract. The +default values are as follows. If (hash\->up_load < load) => +expand. if (hash\->down_load > load) => contract. The \&\fBup_load\fR has a default value of 1 and \fBdown_load\fR has a default value of 2. These numbers can be modified by the application by just playing with the \fBup_load\fR and \fBdown_load\fR variables. The 'load' is kept in a form which is multiplied by 256. So -hash->up_load=8*256; will cause a load of 8 to be set. +hash\->up_load=8*256; will cause a load of 8 to be set. .PP If you are interested in performance the field to watch is num_comp_calls. The hash library keeps track of the 'hash' value for each item so when a lookup is done, the 'hashes' are compared, if there is a match, then a full compare is done, and -hash->num_comp_calls is incremented. If num_comp_calls is not equal +hash\->num_comp_calls is incremented. If num_comp_calls is not equal to num_delete plus num_retrieve it means that your hash function is generating hashes that are the same for different values. It is probably worth changing your hash function if this is the case because @@ -419,12 +421,13 @@ will be much less expensive that 10 calls to your compare function. .Vb 1 \& unsigned long lh_strhash(const char *c); .Ve +.PP Since the \fB\s-1LHASH\s0\fR routines would normally be passed structures, this routine would not normally be passed to \fIlh_new()\fR, rather it would be used in the function passed to \fIlh_new()\fR. .SH "SEE ALSO" .IX Header "SEE ALSO" -lh_stats(3) +\&\fIlh_stats\fR\|(3) .SH "HISTORY" .IX Header "HISTORY" The \fBlhash\fR library is available in all versions of SSLeay and OpenSSL. |
