Tell the user more explicitly what port needs to be installed to get the
[dragonfly.git] / 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.