X-Git-Url: https://gitweb.dragonflybsd.org/dragonfly.git/blobdiff_plain/146eea7d7398c7a41ce9fab02ea8efee39b47a26..405d0527374835c8db91a0484b96467af3df4467:/secure/lib/libcrypto/man/lhash.3 diff --git a/secure/lib/libcrypto/man/lhash.3 b/secure/lib/libcrypto/man/lhash.3 index 10eb6c3fcf..62f4b1434c 100644 --- a/secure/lib/libcrypto/man/lhash.3 +++ b/secure/lib/libcrypto/man/lhash.3 @@ -1,4 +1,4 @@ -.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.14 +.\" Automatically generated by Pod::Man 2.16 (Pod::Simple 3.05) .\" .\" Standard preamble: .\" ======================================================================== @@ -25,11 +25,11 @@ .. .\" 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<>. -.tr \(*W-|\(bv\*(Tr +.\" 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 C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- @@ -48,22 +48,25 @@ . ds R" '' 'br\} .\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" .\" 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 \{\ +.ie \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . nr % 0 . rr F .\} -.\" -.\" For nroff, turn off justification. Always turn off hyphenation; it makes -.\" way too many mistakes in technical documents. -.hy 0 -.if n .na +.el \{\ +. de IX +.. +.\} .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. @@ -129,37 +132,31 @@ .\" ======================================================================== .\" .IX Title "lhash 3" -.TH lhash 3 "2007-03-28" "0.9.8e" "OpenSSL" +.TH lhash 3 "2009-04-11" "0.9.8k" "OpenSSL" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh .SH "NAME" lh_new, lh_free, lh_insert, lh_delete, lh_retrieve, lh_doall, lh_doall_arg, lh_error \- dynamic hash table .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& #include -.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 *); \& typedef void (*LHASH_DOALL_FN_TYPE)(const void *); @@ -196,9 +193,7 @@ the \*(L"doall\*(R" callbacks, are defined as; \& o_type a = (o_type)arg; \e \& 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 *); \& #define IMPLEMENT_LHASH_COMP_FN(f_name,o_type) \e @@ -207,9 +202,7 @@ the \*(L"doall\*(R" callbacks, are defined as; \& o_type b = (o_type)arg2; \e \& 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 *); \& #define IMPLEMENT_LHASH_DOALL_FN(f_name,o_type) \e @@ -217,9 +210,7 @@ the \*(L"doall\*(R" callbacks, are defined as; \& o_type a = (o_type)arg; \e \& 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 *); \& #define IMPLEMENT_LHASH_DOALL_ARG_FN(f_name,o_type,a_type) \e @@ -233,12 +224,12 @@ the \*(L"doall\*(R" callbacks, are defined as; An example of a hash table storing (pointers to) structures of type '\s-1STUFF\s0' could be defined as follows; .PP -.Vb 14 -\& /* Calculates the hash value of 'tohash' (implemented elsewhere) */ +.Vb 10 +\& /* Calculates the hash value of \*(Aqtohash\*(Aq (implemented elsewhere) */ \& unsigned long STUFF_hash(const STUFF *tohash); -\& /* Orders 'arg1' and 'arg2' (implemented elsewhere) */ +\& /* Orders \*(Aqarg1\*(Aq and \*(Aqarg2\*(Aq (implemented elsewhere) */ \& int STUFF_cmp(const STUFF *arg1, const STUFF *arg2); -\& /* Create the type-safe wrapper functions for use in the LHASH internals */ +\& /* Create the type\-safe wrapper functions for use in the LHASH internals */ \& static IMPLEMENT_LHASH_HASH_FN(STUFF_hash, const STUFF *) \& static IMPLEMENT_LHASH_COMP_FN(STUFF_cmp, const STUFF *); \& /* ... */ @@ -276,9 +267,9 @@ the callback is used to cleanup resources for items in the hash table prior to the hashtable itself being deallocated: .PP .Vb 9 -\& /* Cleans up resources belonging to 'a' (this is implemented elsewhere) */ +\& /* Cleans up resources belonging to \*(Aqa\*(Aq (this is implemented elsewhere) */ \& void STUFF_cleanup(STUFF *a); -\& /* Implement a prototype-compatible wrapper for "STUFF_cleanup" */ +\& /* Implement a prototype\-compatible wrapper for "STUFF_cleanup" */ \& IMPLEMENT_LHASH_DOALL_FN(STUFF_cleanup, STUFF *) \& /* ... then later in the code ... */ \& /* So to run "STUFF_cleanup" against all items in a hash table ... */ @@ -308,9 +299,9 @@ type-specific callbacks. An example of this is demonstrated here caller): .PP .Vb 7 -\& /* Prints item 'a' to 'output_bio' (this is implemented elsewhere) */ +\& /* Prints item \*(Aqa\*(Aq to \*(Aqoutput_bio\*(Aq (this is implemented elsewhere) */ \& void STUFF_print(const STUFF *a, BIO *output_bio); -\& /* Implement a prototype-compatible wrapper for "STUFF_print" */ +\& /* Implement a prototype\-compatible wrapper for "STUFF_print" */ \& static IMPLEMENT_LHASH_DOALL_ARG_FN(STUFF_print, const STUFF *, BIO *) \& /* ... then later in the code ... */ \& /* Print out the entire hashtable to a particular BIO */ @@ -344,7 +335,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. +ANSI-C. .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" @@ -360,7 +351,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