contrib/gperf/doc/gperf.1

   1 .\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.022.
   2 .TH GPERF "1" "September 2000" "GNU gperf 2.7.2" FSF
   3 .SH NAME
   4 gperf \- generate a perfect hash function from a key set
   5 .SH SYNOPSIS
   6 .B gperf
   7 [\fIOPTION\fR]... [\fIINPUT-FILE\fR]
   8 .SH DESCRIPTION
   9 GNU `gperf' generates perfect hash functions.
  10 .PP
  11 If a long option shows an argument as mandatory, then it is mandatory
  12 for the equivalent short option also.
  13 .SS "Input file interpretation:"
  14 .TP
  15 \fB\-e\fR, \fB\-\-delimiters\fR=\fIDELIMITER\-LIST\fR
  16 Allow user to provide a string containing delimiters
  17 used to separate keywords from their attributes.
  18 Default is ",\en".
  19 .TP
  20 \fB\-t\fR, \fB\-\-struct\-type\fR
  21 Allows the user to include a structured type
  22 declaration for generated code. Any text before %%
  23 is considered part of the type declaration. Key
  24 words and additional fields may follow this, one
  25 group of fields per line.
  26 .SS "Language for the output code:"
  27 .TP
  28 \fB\-L\fR, \fB\-\-language\fR=\fILANGUAGE\-NAME\fR
  29 Generates code in the specified language. Languages
  30 handled are currently C++, ANSI-C, C, and KR-C. The
  31 default is C.
  32 .SS "Details in the output code:"
  33 .TP
  34 \fB\-K\fR, \fB\-\-slot\-name\fR=\fINAME\fR
  35 Select name of the keyword component in the keyword
  36 structure.
  37 .TP
  38 \fB\-F\fR, \fB\-\-initializer\-suffix\fR=\fIINITIALIZERS\fR
  39 Initializers for additional components in the keyword
  40 structure.
  41 .TP
  42 \fB\-H\fR, \fB\-\-hash\-fn\-name\fR=\fINAME\fR
  43 Specify name of generated hash function. Default is
  44 `hash'.
  45 .TP
  46 \fB\-N\fR, \fB\-\-lookup\-fn\-name\fR=\fINAME\fR
  47 Specify name of generated lookup function. Default
  48 name is `in_word_set'.
  49 .TP
  50 \fB\-Z\fR, \fB\-\-class\-name\fR=\fINAME\fR
  51 Specify name of generated C++ class. Default name is
  52 `Perfect_Hash'.
  53 .TP
  54 \fB\-7\fR, \fB\-\-seven\-bit\fR
  55 Assume 7-bit characters.
  56 .TP
  57 \fB\-c\fR, \fB\-\-compare\-strncmp\fR
  58 Generate comparison code using strncmp rather than
  59 strcmp.
  60 .TP
  61 \fB\-C\fR, \fB\-\-readonly\-tables\fR
  62 Make the contents of generated lookup tables
  63 constant, i.e., readonly.
  64 .TP
  65 \fB\-E\fR, \fB\-\-enum\fR
  66 Define constant values using an enum local to the
  67 lookup function rather than with defines.
  68 .TP
  69 \fB\-I\fR, \fB\-\-includes\fR
  70 Include the necessary system include file <string.h>
  71 at the beginning of the code.
  72 .TP
  73 \fB\-G\fR, \fB\-\-global\fR
  74 Generate the static table of keywords as a static
  75 global variable, rather than hiding it inside of the
  76 lookup function (which is the default behavior).
  77 .TP
  78 \fB\-W\fR, \fB\-\-word\-array\-name\fR=\fINAME\fR
  79 Specify name of word list array. Default name is
  80 `wordlist'.
  81 .TP
  82 \fB\-S\fR, \fB\-\-switch\fR=\fICOUNT\fR
  83 Causes the generated C code to use a switch
  84 statement scheme, rather than an array lookup table.
  85 This can lead to a reduction in both time and space
  86 requirements for some keyfiles. The COUNT argument
  87 determines how many switch statements are generated.
  88 A value of 1 generates 1 switch containing all the
  89 elements, a value of 2 generates 2 tables with 1/2
  90 the elements in each table, etc. If COUNT is very
  91 large, say 1000000, the generated C code does a
  92 binary search.
  93 .TP
  94 \fB\-T\fR, \fB\-\-omit\-struct\-type\fR
  95 Prevents the transfer of the type declaration to the
  96 output file. Use this option if the type is already
  97 defined elsewhere.
  98 .SS "Algorithm employed by gperf:"
  99 .TP
 100 \fB\-k\fR, \fB\-\-key\-positions\fR=\fIKEYS\fR
 101 Select the key positions used in the hash function.
 102 The allowable choices range between 1-126, inclusive.
 103 The positions are separated by commas, ranges may be
 104 used, and key positions may occur in any order.
 105 Also, the meta-character '*' causes the generated
 106 hash function to consider ALL key positions, and $
 107 indicates the ``final character'' of a key, e.g.,
 108 $,1,2,4,6-10.
 109 .TP
 110 \fB\-l\fR, \fB\-\-compare\-strlen\fR
 111 Compare key lengths before trying a string
 112 comparison. This helps cut down on the number of
 113 string comparisons made during the lookup.
 114 .TP
 115 \fB\-D\fR, \fB\-\-duplicates\fR
 116 Handle keywords that hash to duplicate values. This
 117 is useful for certain highly redundant keyword sets.
 118 .TP
 119 \fB\-f\fR, \fB\-\-fast\fR=\fIITERATIONS\fR
 120 Generate the gen-perf.hash function ``fast''. This
 121 decreases gperf's running time at the cost of
 122 minimizing generated table size. The numeric
 123 argument represents the number of times to iterate
 124 when resolving a collision. `0' means ``iterate by
 125 the number of keywords''.
 126 .TP
 127 \fB\-i\fR, \fB\-\-initial\-asso\fR=\fIN\fR
 128 Provide an initial value for the associate values
 129 array. Default is 0. Setting this value larger helps
 130 inflate the size of the final table.
 131 .TP
 132 \fB\-j\fR, \fB\-\-jump\fR=\fIJUMP\-VALUE\fR
 133 Affects the ``jump value'', i.e., how far to advance
 134 the associated character value upon collisions. Must
 135 be an odd number, default is 5.
 136 .TP
 137 \fB\-n\fR, \fB\-\-no\-strlen\fR
 138 Do not include the length of the keyword when
 139 computing the hash function.
 140 .TP
 141 \fB\-o\fR, \fB\-\-occurrence\-sort\fR
 142 Reorders input keys by frequency of occurrence of
 143 the key sets. This should decrease the search time
 144 dramatically.
 145 .TP
 146 \fB\-r\fR, \fB\-\-random\fR
 147 Utilizes randomness to initialize the associated
 148 values table.
 149 .TP
 150 \fB\-s\fR, \fB\-\-size\-multiple\fR=\fIN\fR
 151 Affects the size of the generated hash table. The
 152 numeric argument N indicates ``how many times larger
 153 or smaller'' the associated value range should be,
 154 in relationship to the number of keys, e.g. a value
 155 of 3 means ``allow the maximum associated value to
 156 be about 3 times larger than the number of input
 157 keys.'' Conversely, a value of \fB\-3\fR means ``make the
 158 maximum associated value about 3 times smaller than
 159 the number of input keys. A larger table should
 160 decrease the time required for an unsuccessful
 161 search, at the expense of extra table space. Default
 162 value is 1.
 163 .SS "Informative output:"
 164 .TP
 165 \fB\-h\fR, \fB\-\-help\fR
 166 Print this message.
 167 .TP
 168 \fB\-v\fR, \fB\-\-version\fR
 169 Print the gperf version number.
 170 .TP
 171 \fB\-d\fR, \fB\-\-debug\fR
 172 Enables the debugging option (produces verbose
 173 output to the standard error).
 174 .SH "REPORTING BUGS"
 175 Report bugs to <bug-gnu-utils@gnu.org>.
 176 .SH "SEE ALSO"
 177 The full documentation for
 178 .B gperf
 179 is maintained as a Texinfo manual.  If the
 180 .B info
 181 and
 182 .B gperf
 183 programs are properly installed at your site, the command
 184 .IP
 185 .B info gperf
 186 .PP
 187 should give you access to the complete manual.