GPERF(1)

🦋 GPERF(1) — the FSF girlies' favourite hash generator 💅

okay bestie, sit down, hydrate, because today we're talking about gperf — the GNU one, living in the FSF manual pages, and she is iconic.

---

✨ NAME ✨

gperf — generate a perfect hash function from a key set. yes. that's her whole job. slay.

---

🌸 SYNOPSIS 🌸

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

---

💖 DESCRIPTION 💖

GNU gperf generates perfect hash functions. that's it, that's the vibe, no cap. 🫶

heads up bestie: if a long option shows an argument as mandatory, then it's mandatory for the equivalent short option too. no skipping, no shortcuts. 😤

🎀 Output file location:

• --output-file=FILE — write the output to the file you named. if you don't specify an output file, or if it's -, the results go to standard output. easy peasy. ✨

🦋 Input file interpretation:

• -e, --delimiters=DELIMITER-LIST — you get to hand over a string of delimiters used to separate keywords from their attributes. default is ,.
• -t, --struct-type — lets you include a structured type declaration for the generated code. any text before %% counts as part of that type declaration. key words and extra fields can follow, one group of fields per line.
• --ignore-case — treats upper and lower case ASCII characters as equivalent. note that locale dependent case mappings are ignored — we're ASCII-only here, babes. 🔤

💜 Language for the output code:

• -L, --language=LANGUAGE-NAME — generates code in the language you pick. the languages she handles right now are C++, ANSI-C, C, and KR-C. the default is ANSI-C.

⭐ Details in the output code:

• -K, --slot-name=NAME — pick the name of the keyword component inside the keyword structure.
• -F, --initializer-suffix=INITIALIZERS — initializers for the additional components in the keyword structure.
• -H, --hash-function-name=NAME — specify the name of the generated hash function. default is hash.
• -N, --lookup-function-name=NAME — specify the name of the generated lookup function. default name is in_word_set.
• -Z, --class-name=NAME — specify the name of the generated C++ class. default name is Perfect_Hash.
• -7, --seven-bit — assume 7-bit characters.
• -l, --compare-lengths — compare key lengths before even trying a string comparison. this is necessary if your keywords contain NUL bytes. it also helps cut down on the number of string comparisons made during the lookup. efficiency queen 👑
• -c, --compare-strncmp — generate comparison code using strncmp rather than strcmp.
• -C, --readonly-tables — makes the contents of the generated lookup tables constant, i.e., readonly. don't touch, she's protected. 🙅
• -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, instead of hiding it inside the lookup function (which is the default behavior). she's out and proud now. ✨
• -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 the name of the string pool generated by option --pic. default name is stringpool.
• --null-strings — use NULL strings instead of empty strings for empty keyword table entries.
• --constants-prefix=PREFIX — specify a prefix for the constants like TOTAL_KEYWORDS.
• -W, --word-array-name=NAME — specify the name of the word list array. default name is wordlist.
• --length-table-name=NAME — specify the name of the 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. 💀 wild but okay
• -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. positions are separated by commas, ranges may be used, and key positions may occur in any order. also, the meta-character * makes the generated hash function consider ALL key positions, and $ indicates the "final character" of a key, e.g., $,1,2,4,6-10. okay miss flexibility 💅
• -D, --duplicates — handle keywords that hash to duplicate values. 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. worth it fr fr.
• -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. chaotic but valid 🎲
• -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.
• -h, --help — print this message. (hi.)
• -v, --version — print the gperf version number.
• -d, --debug — enables the debugging option, which produces verbose output to the standard error. not me watching her spill the tea to stderr 🍓

okay tiny formatting note bestie: -h, -v, and -d are hanging out under "Informative output" in the original, so that's where they live. go look up. ⬆️

---

👑 AUTHOR 👑

Written by Douglas C. Schmidt and Bruno Haible. legends only.

---

😭 REPORTING BUGS 😭

Report bugs to <bug-gperf@gnu.org>. she wants to hear it, she wants the feedback, she's not fragile.

---

💜 COPYRIGHT 💜

Copyright © 2025 Free Software Foundation, Inc. License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>

This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law. (translation: she's free and she's yours, but if something breaks, that's on you bestie. no cap.) 💀

---

🧚 SEE ALSO 🧚

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. go read it, iykyk 📖✨

---

and that's the whole page, bestie. this manual page is GNU gperf 3.3, dated April 2025. mwah. 💅🎀🦋 take care of her and she'll take care of your hash table. periodt. 🌈