|
Packit |
b27855 |
.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.23.
|
|
Packit |
b27855 |
.TH GPERF "1" "January 2017" "GNU gperf 3.1" FSF
|
|
Packit |
b27855 |
.SH NAME
|
|
Packit |
b27855 |
gperf \- generate a perfect hash function from a key set
|
|
Packit |
b27855 |
.SH SYNOPSIS
|
|
Packit |
b27855 |
.B gperf
|
|
Packit |
b27855 |
[\fIOPTION\fR]... [\fIINPUT-FILE\fR]
|
|
Packit |
b27855 |
.SH DESCRIPTION
|
|
Packit |
b27855 |
GNU 'gperf' generates perfect hash functions.
|
|
Packit |
b27855 |
.PP
|
|
Packit |
b27855 |
If a long option shows an argument as mandatory, then it is mandatory
|
|
Packit |
b27855 |
for the equivalent short option also.
|
|
Packit |
b27855 |
.SS "Output file location:"
|
|
Packit |
b27855 |
.HP
|
|
Packit |
b27855 |
\fB\-\-output\-file\fR=\fIFILE\fR Write output to specified file.
|
|
Packit |
b27855 |
.PP
|
|
Packit |
b27855 |
The results are written to standard output if no output file is specified
|
|
Packit |
b27855 |
or if it is -.
|
|
Packit |
b27855 |
.SS "Input file interpretation:"
|
|
Packit |
b27855 |
.TP
|
|
Packit |
b27855 |
\fB\-e\fR, \fB\-\-delimiters\fR=\fIDELIMITER\-LIST\fR
|
|
Packit |
b27855 |
Allow user to provide a string containing delimiters
|
|
Packit |
b27855 |
used to separate keywords from their attributes.
|
|
Packit |
b27855 |
Default is ",".
|
|
Packit |
b27855 |
.TP
|
|
Packit |
b27855 |
\fB\-t\fR, \fB\-\-struct\-type\fR
|
|
Packit |
b27855 |
Allows the user to include a structured type
|
|
Packit |
b27855 |
declaration for generated code. Any text before %%
|
|
Packit |
b27855 |
is considered part of the type declaration. Key
|
|
Packit |
b27855 |
words and additional fields may follow this, one
|
|
Packit |
b27855 |
group of fields per line.
|
|
Packit |
b27855 |
.TP
|
|
Packit |
b27855 |
\fB\-\-ignore\-case\fR
|
|
Packit |
b27855 |
Consider upper and lower case ASCII characters as
|
|
Packit |
b27855 |
equivalent. Note that locale dependent case mappings
|
|
Packit |
b27855 |
are ignored.
|
|
Packit |
b27855 |
.SS "Language for the output code:"
|
|
Packit |
b27855 |
.TP
|
|
Packit |
b27855 |
\fB\-L\fR, \fB\-\-language\fR=\fILANGUAGE\-NAME\fR
|
|
Packit |
b27855 |
Generates code in the specified language. Languages
|
|
Packit |
b27855 |
handled are currently C++, ANSI-C, C, and KR-C. The
|
|
Packit |
b27855 |
default is ANSI-C.
|
|
Packit |
b27855 |
.SS "Details in the output code:"
|
|
Packit |
b27855 |
.TP
|
|
Packit |
b27855 |
\fB\-K\fR, \fB\-\-slot\-name\fR=\fINAME\fR
|
|
Packit |
b27855 |
Select name of the keyword component in the keyword
|
|
Packit |
b27855 |
structure.
|
|
Packit |
b27855 |
.TP
|
|
Packit |
b27855 |
\fB\-F\fR, \fB\-\-initializer\-suffix\fR=\fIINITIALIZERS\fR
|
|
Packit |
b27855 |
Initializers for additional components in the keyword
|
|
Packit |
b27855 |
structure.
|
|
Packit |
b27855 |
.TP
|
|
Packit |
b27855 |
\fB\-H\fR, \fB\-\-hash\-function\-name\fR=\fINAME\fR
|
|
Packit |
b27855 |
Specify name of generated hash function. Default is
|
|
Packit |
b27855 |
\&'hash'.
|
|
Packit |
b27855 |
.TP
|
|
Packit |
b27855 |
\fB\-N\fR, \fB\-\-lookup\-function\-name\fR=\fINAME\fR
|
|
Packit |
b27855 |
Specify name of generated lookup function. Default
|
|
Packit |
b27855 |
name is 'in_word_set'.
|
|
Packit |
b27855 |
.TP
|
|
Packit |
b27855 |
\fB\-Z\fR, \fB\-\-class\-name\fR=\fINAME\fR
|
|
Packit |
b27855 |
Specify name of generated C++ class. Default name is
|
|
Packit |
b27855 |
\&'Perfect_Hash'.
|
|
Packit |
b27855 |
.TP
|
|
Packit |
b27855 |
\fB\-7\fR, \fB\-\-seven\-bit\fR
|
|
Packit |
b27855 |
Assume 7-bit characters.
|
|
Packit |
b27855 |
.TP
|
|
Packit |
b27855 |
\fB\-l\fR, \fB\-\-compare\-lengths\fR
|
|
Packit |
b27855 |
Compare key lengths before trying a string
|
|
Packit |
b27855 |
comparison. This is necessary if the keywords
|
|
Packit |
b27855 |
contain NUL bytes. It also helps cut down on the
|
|
Packit |
b27855 |
number of string comparisons made during the lookup.
|
|
Packit |
b27855 |
.TP
|
|
Packit |
b27855 |
\fB\-c\fR, \fB\-\-compare\-strncmp\fR
|
|
Packit |
b27855 |
Generate comparison code using strncmp rather than
|
|
Packit |
b27855 |
strcmp.
|
|
Packit |
b27855 |
.TP
|
|
Packit |
b27855 |
\fB\-C\fR, \fB\-\-readonly\-tables\fR
|
|
Packit |
b27855 |
Make the contents of generated lookup tables
|
|
Packit |
b27855 |
constant, i.e., readonly.
|
|
Packit |
b27855 |
.TP
|
|
Packit |
b27855 |
\fB\-E\fR, \fB\-\-enum\fR
|
|
Packit |
b27855 |
Define constant values using an enum local to the
|
|
Packit |
b27855 |
lookup function rather than with defines.
|
|
Packit |
b27855 |
.TP
|
|
Packit |
b27855 |
\fB\-I\fR, \fB\-\-includes\fR
|
|
Packit |
b27855 |
Include the necessary system include file <string.h>
|
|
Packit |
b27855 |
at the beginning of the code.
|
|
Packit |
b27855 |
.TP
|
|
Packit |
b27855 |
\fB\-G\fR, \fB\-\-global\-table\fR
|
|
Packit |
b27855 |
Generate the static table of keywords as a static
|
|
Packit |
b27855 |
global variable, rather than hiding it inside of the
|
|
Packit |
b27855 |
lookup function (which is the default behavior).
|
|
Packit |
b27855 |
.TP
|
|
Packit |
b27855 |
\fB\-P\fR, \fB\-\-pic\fR
|
|
Packit |
b27855 |
Optimize the generated table for inclusion in shared
|
|
Packit |
b27855 |
libraries. This reduces the startup time of programs
|
|
Packit |
b27855 |
using a shared library containing the generated code.
|
|
Packit |
b27855 |
.TP
|
|
Packit |
b27855 |
\fB\-Q\fR, \fB\-\-string\-pool\-name\fR=\fINAME\fR
|
|
Packit |
b27855 |
Specify name of string pool generated by option \fB\-\-pic\fR.
|
|
Packit |
b27855 |
Default name is 'stringpool'.
|
|
Packit |
b27855 |
.TP
|
|
Packit |
b27855 |
\fB\-\-null\-strings\fR
|
|
Packit |
b27855 |
Use NULL strings instead of empty strings for empty
|
|
Packit |
b27855 |
keyword table entries.
|
|
Packit |
b27855 |
.TP
|
|
Packit |
b27855 |
\fB\-\-constants\-prefix\fR=\fIPREFIX\fR
|
|
Packit |
b27855 |
Specify prefix for the constants like TOTAL_KEYWORDS.
|
|
Packit |
b27855 |
.TP
|
|
Packit |
b27855 |
\fB\-W\fR, \fB\-\-word\-array\-name\fR=\fINAME\fR
|
|
Packit |
b27855 |
Specify name of word list array. Default name is
|
|
Packit |
b27855 |
\&'wordlist'.
|
|
Packit |
b27855 |
.TP
|
|
Packit |
b27855 |
\fB\-\-length\-table\-name\fR=\fINAME\fR
|
|
Packit |
b27855 |
Specify name of length table array. Default name is
|
|
Packit |
b27855 |
\&'lengthtable'.
|
|
Packit |
b27855 |
.TP
|
|
Packit |
b27855 |
\fB\-S\fR, \fB\-\-switch\fR=\fICOUNT\fR
|
|
Packit |
b27855 |
Causes the generated C code to use a switch
|
|
Packit |
b27855 |
statement scheme, rather than an array lookup table.
|
|
Packit |
b27855 |
This can lead to a reduction in both time and space
|
|
Packit |
b27855 |
requirements for some keyfiles. The COUNT argument
|
|
Packit |
b27855 |
determines how many switch statements are generated.
|
|
Packit |
b27855 |
A value of 1 generates 1 switch containing all the
|
|
Packit |
b27855 |
elements, a value of 2 generates 2 tables with 1/2
|
|
Packit |
b27855 |
the elements in each table, etc. If COUNT is very
|
|
Packit |
b27855 |
large, say 1000000, the generated C code does a
|
|
Packit |
b27855 |
binary search.
|
|
Packit |
b27855 |
.TP
|
|
Packit |
b27855 |
\fB\-T\fR, \fB\-\-omit\-struct\-type\fR
|
|
Packit |
b27855 |
Prevents the transfer of the type declaration to the
|
|
Packit |
b27855 |
output file. Use this option if the type is already
|
|
Packit |
b27855 |
defined elsewhere.
|
|
Packit |
b27855 |
.SS "Algorithm employed by gperf:"
|
|
Packit |
b27855 |
.TP
|
|
Packit |
b27855 |
\fB\-k\fR, \fB\-\-key\-positions\fR=\fIKEYS\fR
|
|
Packit |
b27855 |
Select the key positions used in the hash function.
|
|
Packit |
b27855 |
The allowable choices range between 1-255, inclusive.
|
|
Packit |
b27855 |
The positions are separated by commas, ranges may be
|
|
Packit |
b27855 |
used, and key positions may occur in any order.
|
|
Packit |
b27855 |
Also, the meta-character '*' causes the generated
|
|
Packit |
b27855 |
hash function to consider ALL key positions, and $
|
|
Packit |
b27855 |
indicates the "final character" of a key, e.g.,
|
|
Packit |
b27855 |
$,1,2,4,6-10.
|
|
Packit |
b27855 |
.TP
|
|
Packit |
b27855 |
\fB\-D\fR, \fB\-\-duplicates\fR
|
|
Packit |
b27855 |
Handle keywords that hash to duplicate values. This
|
|
Packit |
b27855 |
is useful for certain highly redundant keyword sets.
|
|
Packit |
b27855 |
.TP
|
|
Packit |
b27855 |
\fB\-m\fR, \fB\-\-multiple\-iterations\fR=\fIITERATIONS\fR
|
|
Packit |
b27855 |
Perform multiple choices of the \fB\-i\fR and \fB\-j\fR values,
|
|
Packit |
b27855 |
and choose the best results. This increases the
|
|
Packit |
b27855 |
running time by a factor of ITERATIONS but does a
|
|
Packit |
b27855 |
good job minimizing the generated table size.
|
|
Packit |
b27855 |
.TP
|
|
Packit |
b27855 |
\fB\-i\fR, \fB\-\-initial\-asso\fR=\fIN\fR
|
|
Packit |
b27855 |
Provide an initial value for the associate values
|
|
Packit |
b27855 |
array. Default is 0. Setting this value larger helps
|
|
Packit |
b27855 |
inflate the size of the final table.
|
|
Packit |
b27855 |
.TP
|
|
Packit |
b27855 |
\fB\-j\fR, \fB\-\-jump\fR=\fIJUMP\-VALUE\fR
|
|
Packit |
b27855 |
Affects the "jump value", i.e., how far to advance
|
|
Packit |
b27855 |
the associated character value upon collisions. Must
|
|
Packit |
b27855 |
be an odd number, default is 5.
|
|
Packit |
b27855 |
.TP
|
|
Packit |
b27855 |
\fB\-n\fR, \fB\-\-no\-strlen\fR
|
|
Packit |
b27855 |
Do not include the length of the keyword when
|
|
Packit |
b27855 |
computing the hash function.
|
|
Packit |
b27855 |
.TP
|
|
Packit |
b27855 |
\fB\-r\fR, \fB\-\-random\fR
|
|
Packit |
b27855 |
Utilizes randomness to initialize the associated
|
|
Packit |
b27855 |
values table.
|
|
Packit |
b27855 |
.TP
|
|
Packit |
b27855 |
\fB\-s\fR, \fB\-\-size\-multiple\fR=\fIN\fR
|
|
Packit |
b27855 |
Affects the size of the generated hash table. The
|
|
Packit |
b27855 |
numeric argument N indicates "how many times larger
|
|
Packit |
b27855 |
or smaller" the associated value range should be,
|
|
Packit |
b27855 |
in relationship to the number of keys, e.g. a value
|
|
Packit |
b27855 |
of 3 means "allow the maximum associated value to
|
|
Packit |
b27855 |
be about 3 times larger than the number of input
|
|
Packit |
b27855 |
keys". Conversely, a value of 1/3 means "make the
|
|
Packit |
b27855 |
maximum associated value about 3 times smaller than
|
|
Packit |
b27855 |
the number of input keys". A larger table should
|
|
Packit |
b27855 |
decrease the time required for an unsuccessful
|
|
Packit |
b27855 |
search, at the expense of extra table space. Default
|
|
Packit |
b27855 |
value is 1.
|
|
Packit |
b27855 |
.SS "Informative output:"
|
|
Packit |
b27855 |
.TP
|
|
Packit |
b27855 |
\fB\-h\fR, \fB\-\-help\fR
|
|
Packit |
b27855 |
Print this message.
|
|
Packit |
b27855 |
.TP
|
|
Packit |
b27855 |
\fB\-v\fR, \fB\-\-version\fR
|
|
Packit |
b27855 |
Print the gperf version number.
|
|
Packit |
b27855 |
.TP
|
|
Packit |
b27855 |
\fB\-d\fR, \fB\-\-debug\fR
|
|
Packit |
b27855 |
Enables the debugging option (produces verbose
|
|
Packit |
b27855 |
output to the standard error).
|
|
Packit |
b27855 |
.SH AUTHOR
|
|
Packit |
b27855 |
Written by Douglas C. Schmidt and Bruno Haible.
|
|
Packit |
b27855 |
.SH "REPORTING BUGS"
|
|
Packit |
b27855 |
Report bugs to <bug-gperf@gnu.org>.
|
|
Packit |
b27855 |
.SH COPYRIGHT
|
|
Packit |
b27855 |
Copyright \(co 1989-2017 Free Software Foundation, Inc.
|
|
Packit |
b27855 |
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
|
|
Packit |
b27855 |
.br
|
|
Packit |
b27855 |
This is free software: you are free to change and redistribute it.
|
|
Packit |
b27855 |
There is NO WARRANTY, to the extent permitted by law.
|
|
Packit |
b27855 |
.SH "SEE ALSO"
|
|
Packit |
b27855 |
The full documentation for
|
|
Packit |
b27855 |
.B gperf
|
|
Packit |
b27855 |
is maintained as a Texinfo manual. If the
|
|
Packit |
b27855 |
.B info
|
|
Packit |
b27855 |
and
|
|
Packit |
b27855 |
.B gperf
|
|
Packit |
b27855 |
programs are properly installed at your site, the command
|
|
Packit |
b27855 |
.IP
|
|
Packit |
b27855 |
.B info gperf
|
|
Packit |
b27855 |
.PP
|
|
Packit |
b27855 |
should give you access to the complete manual.
|