Gperf (1) Linux Manual Page

NAME

gperf – generate a perfect hash function from a key set

SYNOPSIS

gperf [OPTION]… [INPUT-FILE]

DESCRIPTION

GNU ‘gperf’ generates perfect hash functions.

If a long option shows an argument as mandatory, then it is mandatory for the equivalent short option also.

Output file location:

–output-file=FILE Write output to specified file.

The results are written to standard output if no output file is specified or if it is -.

Input file interpretation:

-e, –delimiters=DELIMITER-LIST: Allow user to provide a string containing delimiters used to separate keywords from their attributes. Default is ",".
-t, –struct-type: Allows the user to include a structured type declaration for generated code. Any text before %% is considered part of the type declaration. Key words and additional fields may follow this, one group of fields per line.
–ignore-case: Consider upper and lower case ASCII characters as equivalent. Note that locale dependent case mappings are ignored.

Language for the output code:

-L, –language=LANGUAGE-NAME: Generates code in the specified language. Languages handled are currently C++, ANSI-C, C, and KR-C. The default is C.

Details in the output code:

-K, –slot-name=NAME: Select name of the keyword component in the keyword structure.
-F, –initializer-suffix=INITIALIZERS: Initializers for additional components in the keyword structure.
-H, –hash-function-name=NAME: Specify name of generated hash function. Default is ‘hash’.
-N, –lookup-function-name=NAME: Specify name of generated lookup function. Default name is ‘in_word_set’.
-Z, –class-name=NAME: Specify name of generated C++ class. Default name is ‘Perfect_Hash’.
-7, –seven-bit: Assume 7-bit characters.
-l, –compare-lengths: Compare key lengths before trying a string comparison. This is necessary if the keywords contain NUL bytes. It also helps cut down on the number of string comparisons made during the lookup.
-c, –compare-strncmp: Generate comparison code using strncmp rather than strcmp.
-C, –readonly-tables: Make the contents of generated lookup tables constant, i.e., readonly.
-E, –enum: Define constant values using an enum local to the lookup function rather than with defines.
-I, –includes: Include the necessary system include file <string.h> at the beginning of the code.
-G, –global-table: Generate the static table of keywords as a static global variable, rather than hiding it inside of the lookup function (which is the default behavior).
-P, –pic: Optimize the generated table for inclusion in shared libraries. This reduces the startup time of programs using a shared library containing the generated code.
-Q, –string-pool-name=NAME: Specify name of string pool generated by option –pic. Default name is ‘stringpool’.
–null-strings: Use NULL strings instead of empty strings for empty keyword table entries.
-W, –word-array-name=NAME: Specify name of word list array. Default name is ‘wordlist’.
–length-table-name=NAME: Specify name of length table array. Default name is ‘lengthtable’.
-S, –switch=COUNT: Causes the generated C code to use a switch statement scheme, rather than an array lookup table. This can lead to a reduction in both time and space requirements for some keyfiles. The COUNT argument determines how many switch statements are generated. A value of 1 generates 1 switch containing all the elements, a value of 2 generates 2 tables with 1/2 the elements in each table, etc. If COUNT is very large, say 1000000, the generated C code does a binary search.
-T, –omit-struct-type: Prevents the transfer of the type declaration to the output file. Use this option if the type is already defined elsewhere.

Algorithm employed by gperf:

-k, –key-positions=KEYS: Select the key positions used in the hash function. The allowable choices range between 1-255, inclusive. The positions are separated by commas, ranges may be used, and key positions may occur in any order. Also, the meta-character ‘*’ causes the generated hash function to consider ALL key positions, and $ indicates the "final character" of a key, e.g., $,1,2,4,6-10.
-D, –duplicates: Handle keywords that hash to duplicate values. This is useful for certain highly redundant keyword sets.
-m, –multiple-iterations=ITERATIONS: Perform multiple choices of the -i and -j values, and choose the best results. This increases the running time by a factor of ITERATIONS but does a good job minimizing the generated table size.
-i, –initial-asso=N: Provide an initial value for the associate values array. Default is 0. Setting this value larger helps inflate the size of the final table.
-j, –jump=JUMP-VALUE: Affects the "jump value", i.e., how far to advance the associated character value upon collisions. Must be an odd number, default is 5.
-n, –no-strlen: Do not include the length of the keyword when computing the hash function.
-r, –random: Utilizes randomness to initialize the associated values table.
-s, –size-multiple=N: Affects the size of the generated hash table. The numeric argument N indicates "how many times larger or smaller" the associated value range should be, in relationship to the number of keys, e.g. a value of 3 means "allow the maximum associated value to be about 3 times larger than the number of input keys". Conversely, a value of 1/3 means "make the maximum associated value about 3 times smaller than the number of input keys". A larger table should decrease the time required for an unsuccessful search, at the expense of extra table space. Default value is 1.

Informative output:

-h, –help: Print this message.
-v, –version: Print the gperf version number.
-d, –debug: Enables the debugging option (produces verbose output to the standard error).

AUTHOR

Written by Douglas C. Schmidt and Bruno Haible.

REPORTING BUGS

Report bugs to <bug-gnu-gperf [at] gnu.org>.

COPYRIGHT

Copyright © 1989-1998, 2000-2004, 2006-2007, 2009 Free Software Foundation, Inc.
This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

gperf (1) Linux Manual Page