contrib/gperf/doc/gperf.1

   1 .\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.23.
   2 .TH GPERF "1" "May 2007" "GNU gperf 3.0.3" 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 "Output file location:"
  14 .HP
  15 \fB\-\-output\-file\fR=\fIFILE\fR Write output to specified file.
  16 .PP
  17 The results are written to standard output if no output file is specified
  18 or if it is -.
  19 .SS "Input file interpretation:"
  20 .TP
  21 \fB\-e\fR, \fB\-\-delimiters\fR=\fIDELIMITER\-LIST\fR
  22 Allow user to provide a string containing delimiters
  23 used to separate keywords from their attributes.
  24 Default is ",".
  25 .TP
  26 \fB\-t\fR, \fB\-\-struct\-type\fR
  27 Allows the user to include a structured type
  28 declaration for generated code. Any text before %%
  29 is considered part of the type declaration. Key
  30 words and additional fields may follow this, one
  31 group of fields per line.
  32 .TP
  33 \fB\-\-ignore\-case\fR
  34 Consider upper and lower case ASCII characters as
  35 equivalent. Note that locale dependent case mappings
  36 are ignored.
  37 .SS "Language for the output code:"
  38 .TP
  39 \fB\-L\fR, \fB\-\-language\fR=\fILANGUAGE\-NAME\fR
  40 Generates code in the specified language. Languages
  41 handled are currently C++, ANSI-C, C, and KR-C. The
  42 default is C.
  43 .SS "Details in the output code:"
  44 .TP
  45 \fB\-K\fR, \fB\-\-slot\-name\fR=\fINAME\fR
  46 Select name of the keyword component in the keyword
  47 structure.
  48 .TP
  49 \fB\-F\fR, \fB\-\-initializer\-suffix\fR=\fIINITIALIZERS\fR
  50 Initializers for additional components in the keyword
  51 structure.
  52 .TP
  53 \fB\-H\fR, \fB\-\-hash\-function\-name\fR=\fINAME\fR
  54 Specify name of generated hash function. Default is
  55 \&'hash'.
  56 .TP
  57 \fB\-N\fR, \fB\-\-lookup\-function\-name\fR=\fINAME\fR
  58 Specify name of generated lookup function. Default
  59 name is 'in_word_set'.
  60 .TP
  61 \fB\-Z\fR, \fB\-\-class\-name\fR=\fINAME\fR
  62 Specify name of generated C++ class. Default name is
  63 \&'Perfect_Hash'.
  64 .TP
  65 \fB\-7\fR, \fB\-\-seven\-bit\fR
  66 Assume 7-bit characters.
  67 .TP
  68 \fB\-l\fR, \fB\-\-compare\-lengths\fR
  69 Compare key lengths before trying a string
  70 comparison. This is necessary if the keywords
  71 contain NUL bytes. It also helps cut down on the
  72 number of string comparisons made during the lookup.
  73 .TP
  74 \fB\-c\fR, \fB\-\-compare\-strncmp\fR
  75 Generate comparison code using strncmp rather than
  76 strcmp.
  77 .TP
  78 \fB\-C\fR, \fB\-\-readonly\-tables\fR
  79 Make the contents of generated lookup tables
  80 constant, i.e., readonly.
  81 .TP
  82 \fB\-E\fR, \fB\-\-enum\fR
  83 Define constant values using an enum local to the
  84 lookup function rather than with defines.
  85 .TP
  86 \fB\-I\fR, \fB\-\-includes\fR
  87 Include the necessary system include file <string.h>
  88 at the beginning of the code.
  89 .TP
  90 \fB\-G\fR, \fB\-\-global\-table\fR
  91 Generate the static table of keywords as a static
  92 global variable, rather than hiding it inside of the
  93 lookup function (which is the default behavior).
  94 .TP
  95 \fB\-P\fR, \fB\-\-pic\fR
  96 Optimize the generated table for inclusion in shared
  97 libraries.  This reduces the startup time of programs
  98 using a shared library containing the generated code.
  99 .TP
 100 \fB\-Q\fR, \fB\-\-string\-pool\-name\fR=\fINAME\fR
 101 Specify name of string pool generated by option \fB\-\-pic\fR.
 102 Default name is 'stringpool'.
 103 .TP
 104 \fB\-\-null\-strings\fR
 105 Use NULL strings instead of empty strings for empty
 106 keyword table entries.
 107 .TP
 108 \fB\-W\fR, \fB\-\-word\-array\-name\fR=\fINAME\fR
 109 Specify name of word list array. Default name is
 110 \&'wordlist'.
 111 .TP
 112 \fB\-\-length\-table\-name\fR=\fINAME\fR
 113 Specify name of length table array. Default name is
 114 \&'lengthtable'.
 115 .TP
 116 \fB\-S\fR, \fB\-\-switch\fR=\fICOUNT\fR
 117 Causes the generated C code to use a switch
 118 statement scheme, rather than an array lookup table.
 119 This can lead to a reduction in both time and space
 120 requirements for some keyfiles. The COUNT argument
 121 determines how many switch statements are generated.
 122 A value of 1 generates 1 switch containing all the
 123 elements, a value of 2 generates 2 tables with 1/2
 124 the elements in each table, etc. If COUNT is very
 125 large, say 1000000, the generated C code does a
 126 binary search.
 127 .TP
 128 \fB\-T\fR, \fB\-\-omit\-struct\-type\fR
 129 Prevents the transfer of the type declaration to the
 130 output file. Use this option if the type is already
 131 defined elsewhere.
 132 .SS "Algorithm employed by gperf:"
 133 .TP
 134 \fB\-k\fR, \fB\-\-key\-positions\fR=\fIKEYS\fR
 135 Select the key positions used in the hash function.
 136 The allowable choices range between 1-255, inclusive.
 137 The positions are separated by commas, ranges may be
 138 used, and key positions may occur in any order.
 139 Also, the meta-character '*' causes the generated
 140 hash function to consider ALL key positions, and $
 141 indicates the "final character" of a key, e.g.,
 142 $,1,2,4,6-10.
 143 .TP
 144 \fB\-D\fR, \fB\-\-duplicates\fR
 145 Handle keywords that hash to duplicate values. This
 146 is useful for certain highly redundant keyword sets.
 147 .TP
 148 \fB\-m\fR, \fB\-\-multiple\-iterations\fR=\fIITERATIONS\fR
 149 Perform multiple choices of the \fB\-i\fR and \fB\-j\fR values,
 150 and choose the best results. This increases the
 151 running time by a factor of ITERATIONS but does a
 152 good job minimizing the generated table size.
 153 .TP
 154 \fB\-i\fR, \fB\-\-initial\-asso\fR=\fIN\fR
 155 Provide an initial value for the associate values
 156 array. Default is 0. Setting this value larger helps
 157 inflate the size of the final table.
 158 .TP
 159 \fB\-j\fR, \fB\-\-jump\fR=\fIJUMP\-VALUE\fR
 160 Affects the "jump value", i.e., how far to advance
 161 the associated character value upon collisions. Must
 162 be an odd number, default is 5.
 163 .TP
 164 \fB\-n\fR, \fB\-\-no\-strlen\fR
 165 Do not include the length of the keyword when
 166 computing the hash function.
 167 .TP
 168 \fB\-r\fR, \fB\-\-random\fR
 169 Utilizes randomness to initialize the associated
 170 values table.
 171 .TP
 172 \fB\-s\fR, \fB\-\-size\-multiple\fR=\fIN\fR
 173 Affects the size of the generated hash table. The
 174 numeric argument N indicates "how many times larger
 175 or smaller" the associated value range should be,
 176 in relationship to the number of keys, e.g. a value
 177 of 3 means "allow the maximum associated value to
 178 be about 3 times larger than the number of input
 179 keys". Conversely, a value of 1/3 means "make the
 180 maximum associated value about 3 times smaller than
 181 the number of input keys". A larger table should
 182 decrease the time required for an unsuccessful
 183 search, at the expense of extra table space. Default
 184 value is 1.
 185 .SS "Informative output:"
 186 .TP
 187 \fB\-h\fR, \fB\-\-help\fR
 188 Print this message.
 189 .TP
 190 \fB\-v\fR, \fB\-\-version\fR
 191 Print the gperf version number.
 192 .TP
 193 \fB\-d\fR, \fB\-\-debug\fR
 194 Enables the debugging option (produces verbose
 195 output to the standard error).
 196 .SH AUTHOR
 197 Written by Douglas C. Schmidt and Bruno Haible.
 198 .SH "REPORTING BUGS"
 199 Report bugs to <bug-gnu-gperf@gnu.org>.
 200 .SH COPYRIGHT
 201 Copyright \(co 1989-1998, 2000-2004, 2006-2007 Free Software Foundation, Inc.
 202 .br
 203 This is free software; see the source for copying conditions.  There is NO
 204 warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
 205 .SH "SEE ALSO"
 206 The full documentation for
 207 .B gperf
 208 is maintained as a Texinfo manual.  If the
 209 .B info
 210 and
 211 .B gperf
 212 programs are properly installed at your site, the command
 213 .IP
 214 .B info gperf
 215 .PP
 216 should give you access to the complete manual.