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