man pages section 1: User Commands

Exit Print View

Updated: July 2014

gperf (1)


gperf - generate a perfect hash function from a key set


gperf [OPTION]... [INPUT-FILE]


FSF                                                      GPERF(1)

     gperf - generate a perfect hash function from a key set

     gperf [OPTION]... [INPUT-FILE]

     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 declara-
          tion for generated code. Any text before %% is  consid-
          ered  part of the type declaration. Key words and addi-
          tional fields may follow this, one group of fields  per

          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

     -F, --initializer-suffix=INITIALIZERS
          Initializers for additional components in  the  keyword

     -H, --hash-function-name=NAME

GNU gperf 3.0.3       Last change: May 2007                     1

FSF                                                      GPERF(1)

          Specify  name  of  generated  hash function. Default is

     -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

     -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 str-

     -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'.

          Use NULL strings instead of  empty  strings  for  empty

GNU gperf 3.0.3       Last change: May 2007                     2

FSF                                                      GPERF(1)

          keyword table entries.

     -W, --word-array-name=NAME
          Specify  name  of  word  list  array.  Default  name is

          Specify name of length table  array.  Default  name  is

     -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 func-
          tion 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 min-
          imizing 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

GNU gperf 3.0.3       Last change: May 2007                     3

FSF                                                      GPERF(1)

          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

     -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 rela-
          tionship 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).

     Written by Douglas C. Schmidt and Bruno Haible.

     Report bugs to <>.

     Copyright (C) 1989-1998, 2000-2004, 2006-2007 Free  Software
     Foundation, Inc.
     This  is  free  software;  see the source for copying condi-
     tions.  There is NO warranty; not even  for  MERCHANTABILITY

     See   attributes(5)   for   descriptions  of  the  following

GNU gperf 3.0.3       Last change: May 2007                     4

FSF                                                      GPERF(1)


     |Availability   | developer/gperf  |
     |Stability      | Uncommitted      |
     The full documentation for gperf is maintained as a  Texinfo
     manual.   If  the  info  and  gperf  programs  are  properly
     installed at your site, the command

          info gperf

     should give you access to the complete manual.

     This  software  was   built   from   source   available   at    The  original
     community       source       was       downloaded       from

     Further  information about this software can be found on the
     open source community  website  at

GNU gperf 3.0.3       Last change: May 2007                     5