File: gperf_5.html

package info (click to toggle)
gperf 3.0.4-2
links: PTS
area: main
in suites: stretch
size: 3,452 kB
ctags: 790
sloc: exp: 6,432; cpp: 5,627; perl: 2,117; ansic: 889; makefile: 502; sh: 71
file content (720 lines) | stat: -rw-r--r-- 27,185 bytes
parent folder | download | duplicates (2)
<HTML>
<HEAD>
<!-- This HTML file has been created by texi2html 1.52b
     from gperf.texi on 1 February 2009 -->

<META HTTP-EQUIV="content-type" CONTENT="text/html; charset=UTF-8">
<TITLE>Perfect Hash Function Generator - 4  High-Level Description of GNU gperf</TITLE>
</HEAD>
<BODY>
Go to the <A HREF="gperf_1.html">first</A>, <A HREF="gperf_4.html">previous</A>, <A HREF="gperf_6.html">next</A>, <A HREF="gperf_10.html">last</A> section, <A HREF="gperf_toc.html">table of contents</A>.
<P><HR><P>


<H1><A NAME="SEC5" HREF="gperf_toc.html#TOC5">4  High-Level Description of GNU <CODE>gperf</CODE></A></H1>

<P>
The perfect hash function generator <CODE>gperf</CODE> reads a set of
“keywords” from an input file (or from the standard input by
default).  It attempts to derive a perfect hashing function that
recognizes a member of the <EM>static keyword set</EM> with at most a
single probe into the lookup table.  If <CODE>gperf</CODE> succeeds in
generating such a function it produces a pair of C source code routines
that perform hashing and table lookup recognition.  All generated C code
is directed to the standard output.  Command-line options described
below allow you to modify the input and output format to <CODE>gperf</CODE>.

</P>
<P>
By default, <CODE>gperf</CODE> attempts to produce time-efficient code, with
less emphasis on efficient space utilization.  However, several options
exist that permit trading-off execution time for storage space and vice
versa.  In particular, expanding the generated table size produces a
sparse search structure, generally yielding faster searches.
Conversely, you can direct <CODE>gperf</CODE> to utilize a C <CODE>switch</CODE>
statement scheme that minimizes data space storage size.  Furthermore,
using a C <CODE>switch</CODE> may actually speed up the keyword retrieval time
somewhat.  Actual results depend on your C compiler, of course.

</P>
<P>
In general, <CODE>gperf</CODE> assigns values to the bytes it is using
for hashing until some set of values gives each keyword a unique value.
A helpful heuristic is that the larger the hash value range, the easier
it is for <CODE>gperf</CODE> to find and generate a perfect hash function.
Experimentation is the key to getting the most from <CODE>gperf</CODE>.

</P>


<H2><A NAME="SEC6" HREF="gperf_toc.html#TOC6">4.1  Input Format to <CODE>gperf</CODE></A></H2>
<P>
<A NAME="IDX4"></A>
<A NAME="IDX5"></A>
<A NAME="IDX6"></A>
<A NAME="IDX7"></A>
You can control the input file format by varying certain command-line
arguments, in particular the <SAMP>&lsquo;-t&rsquo;</SAMP> option.  The input's appearance
is similar to GNU utilities <CODE>flex</CODE> and <CODE>bison</CODE> (or UNIX
utilities <CODE>lex</CODE> and <CODE>yacc</CODE>).  Here's an outline of the general
format:

</P>

<PRE>
declarations
%%
keywords
%%
functions
</PRE>

<P>
<EM>Unlike</EM> <CODE>flex</CODE> or <CODE>bison</CODE>, the declarations section and
the functions section are optional.  The following sections describe the
input format for each section.

</P>

<P>
It is possible to omit the declaration section entirely, if the <SAMP>&lsquo;-t&rsquo;</SAMP>
option is not given.  In this case the input file begins directly with the
first keyword line, e.g.:

</P>

<PRE>
january
february
march
april
...
</PRE>



<H3><A NAME="SEC7" HREF="gperf_toc.html#TOC7">4.1.1  Declarations</A></H3>

<P>
The keyword input file optionally contains a section for including
arbitrary C declarations and definitions, <CODE>gperf</CODE> declarations that
act like command-line options, as well as for providing a user-supplied
<CODE>struct</CODE>.

</P>



<H4><A NAME="SEC8" HREF="gperf_toc.html#TOC8">4.1.1.1  User-supplied <CODE>struct</CODE></A></H4>

<P>
If the <SAMP>&lsquo;-t&rsquo;</SAMP> option (or, equivalently, the <SAMP>&lsquo;%struct-type&rsquo;</SAMP> declaration)
<EM>is</EM> enabled, you <EM>must</EM> provide a C <CODE>struct</CODE> as the last
component in the declaration section from the input file.  The first
field in this struct must be of type <CODE>char *</CODE> or <CODE>const char *</CODE>
if the <SAMP>&lsquo;-P&rsquo;</SAMP> option is not given, or of type <CODE>int</CODE> if the option
<SAMP>&lsquo;-P&rsquo;</SAMP> (or, equivalently, the <SAMP>&lsquo;%pic&rsquo;</SAMP> declaration) is enabled.
This first field must be called <SAMP>&lsquo;name&rsquo;</SAMP>, although it is possible to modify
its name with the <SAMP>&lsquo;-K&rsquo;</SAMP> option (or, equivalently, the
<SAMP>&lsquo;%define slot-name&rsquo;</SAMP> declaration) described below.

</P>
<P>
Here is a simple example, using months of the year and their attributes as
input:

</P>

<PRE>
struct month { char *name; int number; int days; int leap_days; };
%%
january,   1, 31, 31
february,  2, 28, 29
march,     3, 31, 31
april,     4, 30, 30
may,       5, 31, 31
june,      6, 30, 30
july,      7, 31, 31
august,    8, 31, 31
september, 9, 30, 30
october,  10, 31, 31
november, 11, 30, 30
december, 12, 31, 31
</PRE>

<P>
<A NAME="IDX8"></A>
Separating the <CODE>struct</CODE> declaration from the list of keywords and
other fields are a pair of consecutive percent signs, <SAMP>&lsquo;%%&rsquo;</SAMP>,
appearing left justified in the first column, as in the UNIX utility
<CODE>lex</CODE>.

</P>
<P>
If the <CODE>struct</CODE> has already been declared in an include file, it can
be mentioned in an abbreviated form, like this:

</P>

<PRE>
struct month;
%%
january,   1, 31, 31
...
</PRE>



<H4><A NAME="SEC9" HREF="gperf_toc.html#TOC9">4.1.1.2  Gperf Declarations</A></H4>

<P>
The declaration section can contain <CODE>gperf</CODE> declarations.  They
influence the way <CODE>gperf</CODE> works, like command line options do.
In fact, every such declaration is equivalent to a command line option.
There are three forms of declarations:

</P>

<OL>
<LI>

Declarations without argument, like <SAMP>&lsquo;%compare-lengths&rsquo;</SAMP>.

<LI>

Declarations with an argument, like <SAMP>&lsquo;%switch=<VAR>count</VAR>&rsquo;</SAMP>.

<LI>

Declarations of names of entities in the output file, like
<SAMP>&lsquo;%define lookup-function-name <VAR>name</VAR>&rsquo;</SAMP>.
</OL>

<P>
When a declaration is given both in the input file and as a command line
option, the command-line option's value prevails.

</P>
<P>
The following <CODE>gperf</CODE> declarations are available.

</P>
<DL COMPACT>

<DT><SAMP>&lsquo;%delimiters=<VAR>delimiter-list</VAR>&rsquo;</SAMP>
<DD>
<A NAME="IDX9"></A>
Allows you to provide a string containing delimiters used to
separate keywords from their attributes.  The default is ",".  This
option is essential if you want to use keywords that have embedded
commas or newlines.

<DT><SAMP>&lsquo;%struct-type&rsquo;</SAMP>
<DD>
<A NAME="IDX10"></A>
Allows you to include a <CODE>struct</CODE> type declaration for generated
code; see above for an example.

<DT><SAMP>&lsquo;%ignore-case&rsquo;</SAMP>
<DD>
<A NAME="IDX11"></A>
Consider upper and lower case ASCII characters as equivalent.  The string
comparison will use a case insignificant character comparison.  Note that
locale dependent case mappings are ignored.

<DT><SAMP>&lsquo;%language=<VAR>language-name</VAR>&rsquo;</SAMP>
<DD>
<A NAME="IDX12"></A>
Instructs <CODE>gperf</CODE> to generate code in the language specified by the
option's argument.  Languages handled are currently:

<DL COMPACT>

<DT><SAMP>&lsquo;KR-C&rsquo;</SAMP>
<DD>
Old-style K&#38;R C.  This language is understood by old-style C compilers and
ANSI C compilers, but ANSI C compilers may flag warnings (or even errors)
because of lacking <SAMP>&lsquo;const&rsquo;</SAMP>.

<DT><SAMP>&lsquo;C&rsquo;</SAMP>
<DD>
Common C.  This language is understood by ANSI C compilers, and also by
old-style C compilers, provided that you <CODE>#define const</CODE> to empty
for compilers which don't know about this keyword.

<DT><SAMP>&lsquo;ANSI-C&rsquo;</SAMP>
<DD>
ANSI C.  This language is understood by ANSI C (C89, ISO C90) compilers,
ISO C99 compilers, and C++ compilers.

<DT><SAMP>&lsquo;C++&rsquo;</SAMP>
<DD>
C++.  This language is understood by C++ compilers.
</DL>

The default is C.

<DT><SAMP>&lsquo;%define slot-name <VAR>name</VAR>&rsquo;</SAMP>
<DD>
<A NAME="IDX13"></A>
This declaration is only useful when option <SAMP>&lsquo;-t&rsquo;</SAMP> (or, equivalently, the
<SAMP>&lsquo;%struct-type&rsquo;</SAMP> declaration) has been given.
By default, the program assumes the structure component identifier for
the keyword is <SAMP>&lsquo;name&rsquo;</SAMP>.  This option allows an arbitrary choice of
identifier for this component, although it still must occur as the first
field in your supplied <CODE>struct</CODE>.

<DT><SAMP>&lsquo;%define initializer-suffix <VAR>initializers</VAR>&rsquo;</SAMP>
<DD>
<A NAME="IDX14"></A>
This declaration is only useful when option <SAMP>&lsquo;-t&rsquo;</SAMP> (or, equivalently, the
<SAMP>&lsquo;%struct-type&rsquo;</SAMP> declaration) has been given.
It permits to specify initializers for the structure members following
<VAR>slot-name</VAR> in empty hash table entries.  The list of initializers
should start with a comma.  By default, the emitted code will
zero-initialize structure members following <VAR>slot-name</VAR>.

<DT><SAMP>&lsquo;%define hash-function-name <VAR>name</VAR>&rsquo;</SAMP>
<DD>
<A NAME="IDX15"></A>
Allows you to specify the name for the generated hash function.  Default
name is <SAMP>&lsquo;hash&rsquo;</SAMP>.  This option permits the use of two hash tables in
the same file.

<DT><SAMP>&lsquo;%define lookup-function-name <VAR>name</VAR>&rsquo;</SAMP>
<DD>
<A NAME="IDX16"></A>
Allows you to specify the name for the generated lookup function.
Default name is <SAMP>&lsquo;in_word_set&rsquo;</SAMP>.  This option permits multiple
generated hash functions to be used in the same application.

<DT><SAMP>&lsquo;%define class-name <VAR>name</VAR>&rsquo;</SAMP>
<DD>
<A NAME="IDX17"></A>
This option is only useful when option <SAMP>&lsquo;-L C++&rsquo;</SAMP> (or, equivalently,
the <SAMP>&lsquo;%language=C++&rsquo;</SAMP> declaration) has been given.  It
allows you to specify the name of generated C++ class.  Default name is
<CODE>Perfect_Hash</CODE>.

<DT><SAMP>&lsquo;%7bit&rsquo;</SAMP>
<DD>
<A NAME="IDX18"></A>
This option specifies that all strings that will be passed as arguments
to the generated hash function and the generated lookup function will
solely consist of 7-bit ASCII characters (bytes in the range 0..127).
(Note that the ANSI C functions <CODE>isalnum</CODE> and <CODE>isgraph</CODE> do
<EM>not</EM> guarantee that a byte is in this range.  Only an explicit
test like <SAMP>&lsquo;c &#62;= 'A' &#38;&#38; c &#60;= 'Z'&rsquo;</SAMP> guarantees this.)

<DT><SAMP>&lsquo;%compare-lengths&rsquo;</SAMP>
<DD>
<A NAME="IDX19"></A>
Compare keyword lengths before trying a string comparison.  This option
is mandatory for binary comparisons (see section <A HREF="gperf_5.html#SEC15">4.3  Use of NUL bytes</A>).  It also might
cut down on the number of string comparisons made during the lookup, since
keywords with different lengths are never compared via <CODE>strcmp</CODE>.
However, using <SAMP>&lsquo;%compare-lengths&rsquo;</SAMP> might greatly increase the size of the
generated C code if the lookup table range is large (which implies that
the switch option <SAMP>&lsquo;-S&rsquo;</SAMP> or <SAMP>&lsquo;%switch&rsquo;</SAMP> is not enabled), since the length
table contains as many elements as there are entries in the lookup table.

<DT><SAMP>&lsquo;%compare-strncmp&rsquo;</SAMP>
<DD>
<A NAME="IDX20"></A>
Generates C code that uses the <CODE>strncmp</CODE> function to perform
string comparisons.  The default action is to use <CODE>strcmp</CODE>.

<DT><SAMP>&lsquo;%readonly-tables&rsquo;</SAMP>
<DD>
<A NAME="IDX21"></A>
Makes the contents of all generated lookup tables constant, i.e.,
“readonly”.  Many compilers can generate more efficient code for this
by putting the tables in readonly memory.

<DT><SAMP>&lsquo;%enum&rsquo;</SAMP>
<DD>
<A NAME="IDX22"></A>
Define constant values using an enum local to the lookup function rather
than with #defines.  This also means that different lookup functions can
reside in the same file.  Thanks to James Clark <CODE>&#60;jjc@ai.mit.edu&#62;</CODE>.

<DT><SAMP>&lsquo;%includes&rsquo;</SAMP>
<DD>
<A NAME="IDX23"></A>
Include the necessary system include file, <CODE>&#60;string.h&#62;</CODE>, at the
beginning of the code.  By default, this is not done; the user must
include this header file himself to allow compilation of the code.

<DT><SAMP>&lsquo;%global-table&rsquo;</SAMP>
<DD>
<A NAME="IDX24"></A>
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).

<DT><SAMP>&lsquo;%pic&rsquo;</SAMP>
<DD>
<A NAME="IDX25"></A>
Optimize the generated table for inclusion in shared libraries.  This
reduces the startup time of programs using a shared library containing
the generated code.  If the <SAMP>&lsquo;%struct-type&rsquo;</SAMP> declaration (or,
equivalently, the option <SAMP>&lsquo;-t&rsquo;</SAMP>) is also given, the first field of the
user-defined struct must be of type <SAMP>&lsquo;int&rsquo;</SAMP>, not <SAMP>&lsquo;char *&rsquo;</SAMP>, because
it will contain offsets into the string pool instead of actual strings.
To convert such an offset to a string, you can use the expression
<SAMP>&lsquo;stringpool + <VAR>o</VAR>&rsquo;</SAMP>, where <VAR>o</VAR> is the offset.  The string pool
name can be changed through the <SAMP>&lsquo;%define string-pool-name&rsquo;</SAMP> declaration.

<DT><SAMP>&lsquo;%define string-pool-name <VAR>name</VAR>&rsquo;</SAMP>
<DD>
<A NAME="IDX26"></A>
Allows you to specify the name of the generated string pool created by
the declaration <SAMP>&lsquo;%pic&rsquo;</SAMP> (or, equivalently, the option <SAMP>&lsquo;-P&rsquo;</SAMP>).
The default name is <SAMP>&lsquo;stringpool&rsquo;</SAMP>.  This declaration permits the use of
two hash tables in the same file, with <SAMP>&lsquo;%pic&rsquo;</SAMP> and even when the
<SAMP>&lsquo;%global-table&rsquo;</SAMP> declaration (or, equivalently, the option <SAMP>&lsquo;-G&rsquo;</SAMP>)
is given.

<DT><SAMP>&lsquo;%null-strings&rsquo;</SAMP>
<DD>
<A NAME="IDX27"></A>
Use NULL strings instead of empty strings for empty keyword table entries.
This reduces the startup time of programs using a shared library containing
the generated code (but not as much as the declaration <SAMP>&lsquo;%pic&rsquo;</SAMP>), at the
expense of one more test-and-branch instruction at run time.

<DT><SAMP>&lsquo;%define word-array-name <VAR>name</VAR>&rsquo;</SAMP>
<DD>
<A NAME="IDX28"></A>
Allows you to specify the name for the generated array containing the
hash table.  Default name is <SAMP>&lsquo;wordlist&rsquo;</SAMP>.  This option permits the
use of two hash tables in the same file, even when the option <SAMP>&lsquo;-G&rsquo;</SAMP>
(or, equivalently, the <SAMP>&lsquo;%global-table&rsquo;</SAMP> declaration) is given.

<DT><SAMP>&lsquo;%define length-table-name <VAR>name</VAR>&rsquo;</SAMP>
<DD>
<A NAME="IDX29"></A>
Allows you to specify the name for the generated array containing the
length table.  Default name is <SAMP>&lsquo;lengthtable&rsquo;</SAMP>.  This option permits the
use of two length tables in the same file, even when the option <SAMP>&lsquo;-G&rsquo;</SAMP>
(or, equivalently, the <SAMP>&lsquo;%global-table&rsquo;</SAMP> declaration) is given.

<DT><SAMP>&lsquo;%switch=<VAR>count</VAR>&rsquo;</SAMP>
<DD>
<A NAME="IDX30"></A>
Causes the generated C code to use a <CODE>switch</CODE> statement scheme,
rather than an array lookup table.  This can lead to a reduction in both
time and space requirements for some input files.  The argument to this
option determines how many <CODE>switch</CODE> statements are generated.  A
value of 1 generates 1 <CODE>switch</CODE> containing all the elements, a
value of 2 generates 2 tables with 1/2 the elements in each
<CODE>switch</CODE>, etc.  This is useful since many C compilers cannot
correctly generate code for large <CODE>switch</CODE> statements.  This option
was inspired in part by Keith Bostic's original C program.

<DT><SAMP>&lsquo;%omit-struct-type&rsquo;</SAMP>
<DD>
<A NAME="IDX31"></A>
Prevents the transfer of the type declaration to the output file.  Use
this option if the type is already defined elsewhere.
</DL>



<H4><A NAME="SEC10" HREF="gperf_toc.html#TOC10">4.1.1.3  C Code Inclusion</A></H4>

<P>
<A NAME="IDX32"></A>
<A NAME="IDX33"></A>
Using a syntax similar to GNU utilities <CODE>flex</CODE> and <CODE>bison</CODE>, it
is possible to directly include C source text and comments verbatim into
the generated output file.  This is accomplished by enclosing the region
inside left-justified surrounding <SAMP>&lsquo;%{&rsquo;</SAMP>, <SAMP>&lsquo;%}&rsquo;</SAMP> pairs.  Here is
an input fragment based on the previous example that illustrates this
feature:

</P>

<PRE>
%{
#include &#60;assert.h&#62;
/* This section of code is inserted directly into the output. */
int return_month_days (struct month *months, int is_leap_year);
%}
struct month { char *name; int number; int days; int leap_days; };
%%
january,   1, 31, 31
february,  2, 28, 29
march,     3, 31, 31
...
</PRE>



<H3><A NAME="SEC11" HREF="gperf_toc.html#TOC11">4.1.2  Format for Keyword Entries</A></H3>

<P>
The second input file format section contains lines of keywords and any
associated attributes you might supply.  A line beginning with <SAMP>&lsquo;#&rsquo;</SAMP>
in the first column is considered a comment.  Everything following the
<SAMP>&lsquo;#&rsquo;</SAMP> is ignored, up to and including the following newline.  A line
beginning with <SAMP>&lsquo;%&rsquo;</SAMP> in the first column is an option declaration and
must not occur within the keywords section.

</P>
<P>
The first field of each non-comment line is always the keyword itself.  It
can be given in two ways: as a simple name, i.e., without surrounding
string quotation marks, or as a string enclosed in double-quotes, in
C syntax, possibly with backslash escapes like <CODE>\"</CODE> or <CODE>\234</CODE>
or <CODE>\xa8</CODE>.  In either case, it must start right at the beginning
of the line, without leading whitespace.
In this context, a “field” is considered to extend up to, but
not include, the first blank, comma, or newline.  Here is a simple
example taken from a partial list of C reserved words:

</P>

<PRE>
# These are a few C reserved words, see the c.gperf file 
# for a complete list of ANSI C reserved words.
unsigned
sizeof
switch
signed
if
default
for
while
return
</PRE>

<P>
Note that unlike <CODE>flex</CODE> or <CODE>bison</CODE> the first <SAMP>&lsquo;%%&rsquo;</SAMP> marker
may be elided if the declaration section is empty.

</P>
<P>
Additional fields may optionally follow the leading keyword.  Fields
should be separated by commas, and terminate at the end of line.  What
these fields mean is entirely up to you; they are used to initialize the
elements of the user-defined <CODE>struct</CODE> provided by you in the
declaration section.  If the <SAMP>&lsquo;-t&rsquo;</SAMP> option (or, equivalently, the
<SAMP>&lsquo;%struct-type&rsquo;</SAMP> declaration) is <EM>not</EM> enabled
these fields are simply ignored.  All previous examples except the last
one contain keyword attributes.

</P>


<H3><A NAME="SEC12" HREF="gperf_toc.html#TOC12">4.1.3  Including Additional C Functions</A></H3>

<P>
The optional third section also corresponds closely with conventions
found in <CODE>flex</CODE> and <CODE>bison</CODE>.  All text in this section,
starting at the final <SAMP>&lsquo;%%&rsquo;</SAMP> and extending to the end of the input
file, is included verbatim into the generated output file.  Naturally,
it is your responsibility to ensure that the code contained in this
section is valid C.

</P>


<H3><A NAME="SEC13" HREF="gperf_toc.html#TOC13">4.1.4  Where to place directives for GNU <CODE>indent</CODE>.</A></H3>

<P>
If you want to invoke GNU <CODE>indent</CODE> on a <CODE>gperf</CODE> input file,
you will see that GNU <CODE>indent</CODE> doesn't understand the <SAMP>&lsquo;%%&rsquo;</SAMP>,
<SAMP>&lsquo;%{&rsquo;</SAMP> and <SAMP>&lsquo;%}&rsquo;</SAMP> directives that control <CODE>gperf</CODE>'s
interpretation of the input file.  Therefore you have to insert some
directives for GNU <CODE>indent</CODE>.  More precisely, assuming the most
general input file structure

</P>

<PRE>
declarations part 1
%{
verbatim code
%}
declarations part 2
%%
keywords
%%
functions
</PRE>

<P>
you would insert <SAMP>&lsquo;*INDENT-OFF*&rsquo;</SAMP> and <SAMP>&lsquo;*INDENT-ON*&rsquo;</SAMP> comments
as follows:

</P>

<PRE>
/* *INDENT-OFF* */
declarations part 1
%{
/* *INDENT-ON* */
verbatim code
/* *INDENT-OFF* */
%}
declarations part 2
%%
keywords
%%
/* *INDENT-ON* */
functions
</PRE>



<H2><A NAME="SEC14" HREF="gperf_toc.html#TOC14">4.2  Output Format for Generated C Code with <CODE>gperf</CODE></A></H2>
<P>
<A NAME="IDX34"></A>

</P>
<P>
Several options control how the generated C code appears on the standard 
output.  Two C functions are generated.  They are called <CODE>hash</CODE> and 
<CODE>in_word_set</CODE>, although you may modify their names with a command-line 
option.  Both functions require two arguments, a string, <CODE>char *</CODE> 
<VAR>str</VAR>, and a length parameter, <CODE>int</CODE> <VAR>len</VAR>.  Their default 
function prototypes are as follows:

</P>
<P>
<DL>
<DT><U>Function:</U> unsigned int <B>hash</B> <I>(const char * <VAR>str</VAR>, unsigned int <VAR>len</VAR>)</I>
<DD><A NAME="IDX35"></A>
By default, the generated <CODE>hash</CODE> function returns an integer value
created by adding <VAR>len</VAR> to several user-specified <VAR>str</VAR> byte
positions indexed into an <EM>associated values</EM> table stored in a
local static array.  The associated values table is constructed
internally by <CODE>gperf</CODE> and later output as a static local C array
called <SAMP>&lsquo;hash_table&rsquo;</SAMP>.  The relevant selected positions (i.e. indices
into <VAR>str</VAR>) are specified via the <SAMP>&lsquo;-k&rsquo;</SAMP> option when running
<CODE>gperf</CODE>, as detailed in the <EM>Options</EM> section below (see section <A HREF="gperf_6.html#SEC17">5  Invoking <CODE>gperf</CODE></A>).
</DL>

</P>
<P>
<DL>
<DT><U>Function:</U>  <B>in_word_set</B> <I>(const char * <VAR>str</VAR>, unsigned int <VAR>len</VAR>)</I>
<DD><A NAME="IDX36"></A>
If <VAR>str</VAR> is in the keyword set, returns a pointer to that
keyword.  More exactly, if the option <SAMP>&lsquo;-t&rsquo;</SAMP> (or, equivalently, the
<SAMP>&lsquo;%struct-type&rsquo;</SAMP> declaration) was given, it returns
a pointer to the matching keyword's structure.  Otherwise it returns
<CODE>NULL</CODE>.
</DL>

</P>
<P>
If the option <SAMP>&lsquo;-c&rsquo;</SAMP> (or, equivalently, the <SAMP>&lsquo;%compare-strncmp&rsquo;</SAMP>
declaration) is not used, <VAR>str</VAR> must be a NUL terminated
string of exactly length <VAR>len</VAR>.  If <SAMP>&lsquo;-c&rsquo;</SAMP> (or, equivalently, the
<SAMP>&lsquo;%compare-strncmp&rsquo;</SAMP> declaration) is used, <VAR>str</VAR> must
simply be an array of <VAR>len</VAR> bytes and does not need to be NUL
terminated.

</P>
<P>
The code generated for these two functions is affected by the following
options:

</P>
<DL COMPACT>

<DT><SAMP>&lsquo;-t&rsquo;</SAMP>
<DD>
<DT><SAMP>&lsquo;--struct-type&rsquo;</SAMP>
<DD>
Make use of the user-defined <CODE>struct</CODE>.

<DT><SAMP>&lsquo;-S <VAR>total-switch-statements</VAR>&rsquo;</SAMP>
<DD>
<DT><SAMP>&lsquo;--switch=<VAR>total-switch-statements</VAR>&rsquo;</SAMP>
<DD>
<A NAME="IDX37"></A>
Generate 1 or more C <CODE>switch</CODE> statement rather than use a large,
(and potentially sparse) static array.  Although the exact time and
space savings of this approach vary according to your C compiler's
degree of optimization, this method often results in smaller and faster
code.
</DL>

<P>
If the <SAMP>&lsquo;-t&rsquo;</SAMP> and <SAMP>&lsquo;-S&rsquo;</SAMP> options (or, equivalently, the
<SAMP>&lsquo;%struct-type&rsquo;</SAMP> and <SAMP>&lsquo;%switch&rsquo;</SAMP> declarations) are omitted, the default
action
is to generate a <CODE>char *</CODE> array containing the keywords, together with
additional empty strings used for padding the array.  By experimenting
with the various input and output options, and timing the resulting C
code, you can determine the best option choices for different keyword
set characteristics.

</P>


<H2><A NAME="SEC15" HREF="gperf_toc.html#TOC15">4.3  Use of NUL bytes</A></H2>
<P>
<A NAME="IDX38"></A>

</P>
<P>
By default, the code generated by <CODE>gperf</CODE> operates on zero
terminated strings, the usual representation of strings in C.  This means
that the keywords in the input file must not contain NUL bytes,
and the <VAR>str</VAR> argument passed to <CODE>hash</CODE> or <CODE>in_word_set</CODE>
must be NUL terminated and have exactly length <VAR>len</VAR>.

</P>
<P>
If option <SAMP>&lsquo;-c&rsquo;</SAMP> (or, equivalently, the <SAMP>&lsquo;%compare-strncmp&rsquo;</SAMP>
declaration) is used, then the <VAR>str</VAR> argument does not need
to be NUL terminated.  The code generated by <CODE>gperf</CODE> will only
access the first <VAR>len</VAR>, not <VAR>len+1</VAR>, bytes starting at <VAR>str</VAR>.
However, the keywords in the input file still must not contain NUL
bytes.

</P>
<P>
If option <SAMP>&lsquo;-l&rsquo;</SAMP> (or, equivalently, the <SAMP>&lsquo;%compare-lengths&rsquo;</SAMP>
declaration) is used, then the hash table performs binary
comparison.  The keywords in the input file may contain NUL bytes,
written in string syntax as <CODE>\000</CODE> or <CODE>\x00</CODE>, and the code
generated by <CODE>gperf</CODE> will treat NUL like any other byte.
Also, in this case the <SAMP>&lsquo;-c&rsquo;</SAMP> option (or, equivalently, the
<SAMP>&lsquo;%compare-strncmp&rsquo;</SAMP> declaration) is ignored.

</P>


<H2><A NAME="SEC16" HREF="gperf_toc.html#TOC16">4.4  The Copyright of the Output</A></H2>
<P>
<A NAME="IDX39"></A>

</P>
<P>
<CODE>gperf</CODE> is under GPL, but that does not cause the output produced
by <CODE>gperf</CODE> to be under GPL.  The reason is that the output contains
only small pieces of text that come directly from <CODE>gperf</CODE>'s source
code -- only about 7 lines long, too small for being significant --, and
therefore the output is not a “work based on <CODE>gperf</CODE>” (in the
sense of the GPL version 3).

</P>
<P>
On the other hand, the output produced by <CODE>gperf</CODE> contains
essentially all of the input file.  Therefore the output is a
“derivative work” of the input (in the sense of U.S. copyright law);
and its copyright status depends on the copyright of the input.  For most
software licenses, the result is that the the output is under the same
license, with the same copyright holder, as the input that was passed to
<CODE>gperf</CODE>.

</P>
<P><HR><P>
Go to the <A HREF="gperf_1.html">first</A>, <A HREF="gperf_4.html">previous</A>, <A HREF="gperf_6.html">next</A>, <A HREF="gperf_10.html">last</A> section, <A HREF="gperf_toc.html">table of contents</A>.
</BODY>
</HTML>