diff options
Diffstat (limited to 'doc/gperf_5.html')
| -rw-r--r-- | doc/gperf_5.html | 264 |
1 files changed, 146 insertions, 118 deletions
diff --git a/doc/gperf_5.html b/doc/gperf_5.html index 7cfe024..7bc830f 100644 --- a/doc/gperf_5.html +++ b/doc/gperf_5.html @@ -1,22 +1,23 @@ <HTML> <HEAD> -<!-- This HTML file has been created by texi2html 1.51 - from gperf.texi on 31 March 2007 --> +<!-- This HTML file has been created by texi2html 1.52b + from gperf.texi on 1 February 2009 --> -<TITLE>Perfect Hash Function Generator - 3 High-Level Description of GNU gperf</TITLE> +<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="SEC7" HREF="gperf_toc.html#TOC7">3 High-Level Description of GNU <CODE>gperf</CODE></A></H1> +<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 +“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 <STRONG>static keyword set</STRONG> with at most a +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 @@ -46,14 +47,14 @@ Experimentation is the key to getting the most from <CODE>gperf</CODE>. </P> -<H2><A NAME="SEC8" HREF="gperf_toc.html#TOC8">3.1 Input Format to <CODE>gperf</CODE></A></H2> +<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>`-t'</SAMP> option. The input's appearance +arguments, in particular the <SAMP>‘-t’</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: @@ -76,7 +77,7 @@ input format for each section. </P> <P> -It is possible to omit the declaration section entirely, if the <SAMP>`-t'</SAMP> +It is possible to omit the declaration section entirely, if the <SAMP>‘-t’</SAMP> option is not given. In this case the input file begins directly with the first keyword line, e.g.: @@ -92,7 +93,7 @@ april -<H3><A NAME="SEC9" HREF="gperf_toc.html#TOC9">3.1.1 Declarations</A></H3> +<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 @@ -104,18 +105,18 @@ act like command-line options, as well as for providing a user-supplied -<H4><A NAME="SEC10" HREF="gperf_toc.html#TOC10">3.1.1.1 User-supplied <CODE>struct</CODE></A></H4> +<H4><A NAME="SEC8" HREF="gperf_toc.html#TOC8">4.1.1.1 User-supplied <CODE>struct</CODE></A></H4> <P> -If the <SAMP>`-t'</SAMP> option (or, equivalently, the <SAMP>`%struct-type'</SAMP> declaration) +If the <SAMP>‘-t’</SAMP> option (or, equivalently, the <SAMP>‘%struct-type’</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>`-P'</SAMP> option is not given, or of type <CODE>int</CODE> if the option -<SAMP>`-P'</SAMP> (or, equivalently, the <SAMP>`%pic'</SAMP> declaration) is enabled. -This first field must be called <SAMP>`name'</SAMP>, although it is possible to modify -its name with the <SAMP>`-K'</SAMP> option (or, equivalently, the -<SAMP>`%define slot-name'</SAMP> declaration) described below. +if the <SAMP>‘-P’</SAMP> option is not given, or of type <CODE>int</CODE> if the option +<SAMP>‘-P’</SAMP> (or, equivalently, the <SAMP>‘%pic’</SAMP> declaration) is enabled. +This first field must be called <SAMP>‘name’</SAMP>, although it is possible to modify +its name with the <SAMP>‘-K’</SAMP> option (or, equivalently, the +<SAMP>‘%define slot-name’</SAMP> declaration) described below. </P> <P> @@ -144,7 +145,7 @@ december, 12, 31, 31 <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>`%%'</SAMP>, +other fields are a pair of consecutive percent signs, <SAMP>‘%%’</SAMP>, appearing left justified in the first column, as in the UNIX utility <CODE>lex</CODE>. @@ -164,7 +165,7 @@ january, 1, 31, 31 -<H4><A NAME="SEC11" HREF="gperf_toc.html#TOC11">3.1.1.2 Gperf Declarations</A></H4> +<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 @@ -177,16 +178,16 @@ There are three forms of declarations: <OL> <LI> -Declarations without argument, like <SAMP>`%compare-lengths'</SAMP>. +Declarations without argument, like <SAMP>‘%compare-lengths’</SAMP>. <LI> -Declarations with an argument, like <SAMP>`%switch=<VAR>count</VAR>'</SAMP>. +Declarations with an argument, like <SAMP>‘%switch=<VAR>count</VAR>’</SAMP>. <LI> Declarations of names of entities in the output file, like -<SAMP>`%define lookup-function-name <VAR>name</VAR>'</SAMP>. +<SAMP>‘%define lookup-function-name <VAR>name</VAR>’</SAMP>. </OL> <P> @@ -200,7 +201,7 @@ The following <CODE>gperf</CODE> declarations are available. </P> <DL COMPACT> -<DT><SAMP>`%delimiters=<VAR>delimiter-list</VAR>'</SAMP> +<DT><SAMP>‘%delimiters=<VAR>delimiter-list</VAR>’</SAMP> <DD> <A NAME="IDX9"></A> Allows you to provide a string containing delimiters used to @@ -208,20 +209,20 @@ 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>`%struct-type'</SAMP> +<DT><SAMP>‘%struct-type’</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>`%ignore-case'</SAMP> +<DT><SAMP>‘%ignore-case’</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>`%language=<VAR>language-name</VAR>'</SAMP> +<DT><SAMP>‘%language=<VAR>language-name</VAR>’</SAMP> <DD> <A NAME="IDX12"></A> Instructs <CODE>gperf</CODE> to generate code in the language specified by the @@ -229,72 +230,73 @@ option's argument. Languages handled are currently: <DL COMPACT> -<DT><SAMP>`KR-C'</SAMP> +<DT><SAMP>‘KR-C’</SAMP> <DD> Old-style K&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>`const'</SAMP>. +because of lacking <SAMP>‘const’</SAMP>. -<DT><SAMP>`C'</SAMP> +<DT><SAMP>‘C’</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>`ANSI-C'</SAMP> +<DT><SAMP>‘ANSI-C’</SAMP> <DD> -ANSI C. This language is understood by ANSI C compilers and C++ compilers. +ANSI C. This language is understood by ANSI C (C89, ISO C90) compilers, +ISO C99 compilers, and C++ compilers. -<DT><SAMP>`C++'</SAMP> +<DT><SAMP>‘C++’</SAMP> <DD> C++. This language is understood by C++ compilers. </DL> The default is C. -<DT><SAMP>`%define slot-name <VAR>name</VAR>'</SAMP> +<DT><SAMP>‘%define slot-name <VAR>name</VAR>’</SAMP> <DD> <A NAME="IDX13"></A> -This declaration is only useful when option <SAMP>`-t'</SAMP> (or, equivalently, the -<SAMP>`%struct-type'</SAMP> declaration) has been given. +This declaration is only useful when option <SAMP>‘-t’</SAMP> (or, equivalently, the +<SAMP>‘%struct-type’</SAMP> declaration) has been given. By default, the program assumes the structure component identifier for -the keyword is <SAMP>`name'</SAMP>. This option allows an arbitrary choice of +the keyword is <SAMP>‘name’</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>`%define initializer-suffix <VAR>initializers</VAR>'</SAMP> +<DT><SAMP>‘%define initializer-suffix <VAR>initializers</VAR>’</SAMP> <DD> <A NAME="IDX14"></A> -This declaration is only useful when option <SAMP>`-t'</SAMP> (or, equivalently, the -<SAMP>`%struct-type'</SAMP> declaration) has been given. +This declaration is only useful when option <SAMP>‘-t’</SAMP> (or, equivalently, the +<SAMP>‘%struct-type’</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>`%define hash-function-name <VAR>name</VAR>'</SAMP> +<DT><SAMP>‘%define hash-function-name <VAR>name</VAR>’</SAMP> <DD> <A NAME="IDX15"></A> Allows you to specify the name for the generated hash function. Default -name is <SAMP>`hash'</SAMP>. This option permits the use of two hash tables in +name is <SAMP>‘hash’</SAMP>. This option permits the use of two hash tables in the same file. -<DT><SAMP>`%define lookup-function-name <VAR>name</VAR>'</SAMP> +<DT><SAMP>‘%define lookup-function-name <VAR>name</VAR>’</SAMP> <DD> <A NAME="IDX16"></A> Allows you to specify the name for the generated lookup function. -Default name is <SAMP>`in_word_set'</SAMP>. This option permits multiple +Default name is <SAMP>‘in_word_set’</SAMP>. This option permits multiple generated hash functions to be used in the same application. -<DT><SAMP>`%define class-name <VAR>name</VAR>'</SAMP> +<DT><SAMP>‘%define class-name <VAR>name</VAR>’</SAMP> <DD> <A NAME="IDX17"></A> -This option is only useful when option <SAMP>`-L C++'</SAMP> (or, equivalently, -the <SAMP>`%language=C++'</SAMP> declaration) has been given. It +This option is only useful when option <SAMP>‘-L C++’</SAMP> (or, equivalently, +the <SAMP>‘%language=C++’</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>`%7bit'</SAMP> +<DT><SAMP>‘%7bit’</SAMP> <DD> <A NAME="IDX18"></A> This option specifies that all strings that will be passed as arguments @@ -302,102 +304,102 @@ 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>`c >= 'A' && c <= 'Z''</SAMP> guarantees this.) +test like <SAMP>‘c >= 'A' && c <= 'Z'’</SAMP> guarantees this.) -<DT><SAMP>`%compare-lengths'</SAMP> +<DT><SAMP>‘%compare-lengths’</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#SEC17">3.3 Use of NUL bytes</A>). It also might +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>`%compare-lengths'</SAMP> might greatly increase the size of the +However, using <SAMP>‘%compare-lengths’</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>`-S'</SAMP> or <SAMP>`%switch'</SAMP> is not enabled), since the length +the switch option <SAMP>‘-S’</SAMP> or <SAMP>‘%switch’</SAMP> is not enabled), since the length table contains as many elements as there are entries in the lookup table. -<DT><SAMP>`%compare-strncmp'</SAMP> +<DT><SAMP>‘%compare-strncmp’</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>`%readonly-tables'</SAMP> +<DT><SAMP>‘%readonly-tables’</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 +“readonly”. Many compilers can generate more efficient code for this by putting the tables in readonly memory. -<DT><SAMP>`%enum'</SAMP> +<DT><SAMP>‘%enum’</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><jjc@ai.mit.edu></CODE>. -<DT><SAMP>`%includes'</SAMP> +<DT><SAMP>‘%includes’</SAMP> <DD> <A NAME="IDX23"></A> Include the necessary system include file, <CODE><string.h></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>`%global-table'</SAMP> +<DT><SAMP>‘%global-table’</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>`%pic'</SAMP> +<DT><SAMP>‘%pic’</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>`%struct-type'</SAMP> declaration (or, -equivalently, the option <SAMP>`-t'</SAMP>) is also given, the first field of the -user-defined struct must be of type <SAMP>`int'</SAMP>, not <SAMP>`char *'</SAMP>, because +the generated code. If the <SAMP>‘%struct-type’</SAMP> declaration (or, +equivalently, the option <SAMP>‘-t’</SAMP>) is also given, the first field of the +user-defined struct must be of type <SAMP>‘int’</SAMP>, not <SAMP>‘char *’</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>`stringpool + <VAR>o</VAR>'</SAMP>, where <VAR>o</VAR> is the offset. The string pool -name can be changed through the <SAMP>`%define string-pool-name'</SAMP> declaration. +<SAMP>‘stringpool + <VAR>o</VAR>’</SAMP>, where <VAR>o</VAR> is the offset. The string pool +name can be changed through the <SAMP>‘%define string-pool-name’</SAMP> declaration. -<DT><SAMP>`%define string-pool-name <VAR>name</VAR>'</SAMP> +<DT><SAMP>‘%define string-pool-name <VAR>name</VAR>’</SAMP> <DD> <A NAME="IDX26"></A> Allows you to specify the name of the generated string pool created by -the declaration <SAMP>`%pic'</SAMP> (or, equivalently, the option <SAMP>`-P'</SAMP>). -The default name is <SAMP>`stringpool'</SAMP>. This declaration permits the use of -two hash tables in the same file, with <SAMP>`%pic'</SAMP> and even when the -<SAMP>`%global-table'</SAMP> declaration (or, equivalently, the option <SAMP>`-G'</SAMP>) +the declaration <SAMP>‘%pic’</SAMP> (or, equivalently, the option <SAMP>‘-P’</SAMP>). +The default name is <SAMP>‘stringpool’</SAMP>. This declaration permits the use of +two hash tables in the same file, with <SAMP>‘%pic’</SAMP> and even when the +<SAMP>‘%global-table’</SAMP> declaration (or, equivalently, the option <SAMP>‘-G’</SAMP>) is given. -<DT><SAMP>`%null-strings'</SAMP> +<DT><SAMP>‘%null-strings’</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>`%pic'</SAMP>), at the +the generated code (but not as much as the declaration <SAMP>‘%pic’</SAMP>), at the expense of one more test-and-branch instruction at run time. -<DT><SAMP>`%define word-array-name <VAR>name</VAR>'</SAMP> +<DT><SAMP>‘%define word-array-name <VAR>name</VAR>’</SAMP> <DD> <A NAME="IDX28"></A> Allows you to specify the name for the generated array containing the -hash table. Default name is <SAMP>`wordlist'</SAMP>. This option permits the -use of two hash tables in the same file, even when the option <SAMP>`-G'</SAMP> -(or, equivalently, the <SAMP>`%global-table'</SAMP> declaration) is given. +hash table. Default name is <SAMP>‘wordlist’</SAMP>. This option permits the +use of two hash tables in the same file, even when the option <SAMP>‘-G’</SAMP> +(or, equivalently, the <SAMP>‘%global-table’</SAMP> declaration) is given. -<DT><SAMP>`%define length-table-name <VAR>name</VAR>'</SAMP> +<DT><SAMP>‘%define length-table-name <VAR>name</VAR>’</SAMP> <DD> <A NAME="IDX29"></A> Allows you to specify the name for the generated array containing the -length table. Default name is <SAMP>`lengthtable'</SAMP>. This option permits the -use of two length tables in the same file, even when the option <SAMP>`-G'</SAMP> -(or, equivalently, the <SAMP>`%global-table'</SAMP> declaration) is given. +length table. Default name is <SAMP>‘lengthtable’</SAMP>. This option permits the +use of two length tables in the same file, even when the option <SAMP>‘-G’</SAMP> +(or, equivalently, the <SAMP>‘%global-table’</SAMP> declaration) is given. -<DT><SAMP>`%switch=<VAR>count</VAR>'</SAMP> +<DT><SAMP>‘%switch=<VAR>count</VAR>’</SAMP> <DD> <A NAME="IDX30"></A> Causes the generated C code to use a <CODE>switch</CODE> statement scheme, @@ -410,7 +412,7 @@ value of 2 generates 2 tables with 1/2 the elements in each correctly generate code for large <CODE>switch</CODE> statements. This option was inspired in part by Keith Bostic's original C program. -<DT><SAMP>`%omit-struct-type'</SAMP> +<DT><SAMP>‘%omit-struct-type’</SAMP> <DD> <A NAME="IDX31"></A> Prevents the transfer of the type declaration to the output file. Use @@ -419,7 +421,7 @@ this option if the type is already defined elsewhere. -<H4><A NAME="SEC12" HREF="gperf_toc.html#TOC12">3.1.1.3 C Code Inclusion</A></H4> +<H4><A NAME="SEC10" HREF="gperf_toc.html#TOC10">4.1.1.3 C Code Inclusion</A></H4> <P> <A NAME="IDX32"></A> @@ -427,7 +429,7 @@ this option if the type is already defined elsewhere. 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>`%{'</SAMP>, <SAMP>`%}'</SAMP> pairs. Here is +inside left-justified surrounding <SAMP>‘%{’</SAMP>, <SAMP>‘%}’</SAMP> pairs. Here is an input fragment based on the previous example that illustrates this feature: @@ -449,14 +451,14 @@ march, 3, 31, 31 -<H3><A NAME="SEC13" HREF="gperf_toc.html#TOC13">3.1.2 Format for Keyword Entries</A></H3> +<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>`#'</SAMP> +associated attributes you might supply. A line beginning with <SAMP>‘#’</SAMP> in the first column is considered a comment. Everything following the -<SAMP>`#'</SAMP> is ignored, up to and including the following newline. A line -beginning with <SAMP>`%'</SAMP> in the first column is an option declaration and +<SAMP>‘#’</SAMP> is ignored, up to and including the following newline. A line +beginning with <SAMP>‘%’</SAMP> in the first column is an option declaration and must not occur within the keywords section. </P> @@ -467,7 +469,7 @@ 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 +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: @@ -488,7 +490,7 @@ return </PRE> <P> -Note that unlike <CODE>flex</CODE> or <CODE>bison</CODE> the first <SAMP>`%%'</SAMP> marker +Note that unlike <CODE>flex</CODE> or <CODE>bison</CODE> the first <SAMP>‘%%’</SAMP> marker may be elided if the declaration section is empty. </P> @@ -497,20 +499,20 @@ 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>`-t'</SAMP> option (or, equivalently, the -<SAMP>`%struct-type'</SAMP> declaration) is <EM>not</EM> enabled +declaration section. If the <SAMP>‘-t’</SAMP> option (or, equivalently, the +<SAMP>‘%struct-type’</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="SEC14" HREF="gperf_toc.html#TOC14">3.1.3 Including Additional C Functions</A></H3> +<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>`%%'</SAMP> and extending to the end of the input +starting at the final <SAMP>‘%%’</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. @@ -518,12 +520,12 @@ section is valid C. </P> -<H3><A NAME="SEC15" HREF="gperf_toc.html#TOC15">3.1.4 Where to place directives for GNU <CODE>indent</CODE>.</A></H3> +<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>`%%'</SAMP>, -<SAMP>`%{'</SAMP> and <SAMP>`%}'</SAMP> directives that control <CODE>gperf</CODE>'s +you will see that GNU <CODE>indent</CODE> doesn't understand the <SAMP>‘%%’</SAMP>, +<SAMP>‘%{’</SAMP> and <SAMP>‘%}’</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 @@ -543,7 +545,7 @@ functions </PRE> <P> -you would insert <SAMP>`*INDENT-OFF*'</SAMP> and <SAMP>`*INDENT-ON*'</SAMP> comments +you would insert <SAMP>‘*INDENT-OFF*’</SAMP> and <SAMP>‘*INDENT-ON*’</SAMP> comments as follows: </P> @@ -566,7 +568,7 @@ functions -<H2><A NAME="SEC16" HREF="gperf_toc.html#TOC16">3.2 Output Format for Generated C Code with <CODE>gperf</CODE></A></H2> +<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> @@ -586,12 +588,12 @@ function prototypes are as follows: <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 <STRONG>associated values</STRONG> table stored in a +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>`hash_table'</SAMP>. The relevant selected positions (i.e. indices -into <VAR>str</VAR>) are specified via the <SAMP>`-k'</SAMP> option when running -<CODE>gperf</CODE>, as detailed in the <EM>Options</EM> section below (see section <A HREF="gperf_6.html#SEC18">4 Invoking <CODE>gperf</CODE></A>). +called <SAMP>‘hash_table’</SAMP>. The relevant selected positions (i.e. indices +into <VAR>str</VAR>) are specified via the <SAMP>‘-k’</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> @@ -600,18 +602,18 @@ into <VAR>str</VAR>) are specified via the <SAMP>`-k'</SAMP> option when running <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>`-t'</SAMP> (or, equivalently, the -<SAMP>`%struct-type'</SAMP> declaration) was given, it returns +keyword. More exactly, if the option <SAMP>‘-t’</SAMP> (or, equivalently, the +<SAMP>‘%struct-type’</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>`-c'</SAMP> (or, equivalently, the <SAMP>`%compare-strncmp'</SAMP> +If the option <SAMP>‘-c’</SAMP> (or, equivalently, the <SAMP>‘%compare-strncmp’</SAMP> declaration) is not used, <VAR>str</VAR> must be a NUL terminated -string of exactly length <VAR>len</VAR>. If <SAMP>`-c'</SAMP> (or, equivalently, the -<SAMP>`%compare-strncmp'</SAMP> declaration) is used, <VAR>str</VAR> must +string of exactly length <VAR>len</VAR>. If <SAMP>‘-c’</SAMP> (or, equivalently, the +<SAMP>‘%compare-strncmp’</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. @@ -623,15 +625,15 @@ options: </P> <DL COMPACT> -<DT><SAMP>`-t'</SAMP> +<DT><SAMP>‘-t’</SAMP> <DD> -<DT><SAMP>`--struct-type'</SAMP> +<DT><SAMP>‘--struct-type’</SAMP> <DD> Make use of the user-defined <CODE>struct</CODE>. -<DT><SAMP>`-S <VAR>total-switch-statements</VAR>'</SAMP> +<DT><SAMP>‘-S <VAR>total-switch-statements</VAR>’</SAMP> <DD> -<DT><SAMP>`--switch=<VAR>total-switch-statements</VAR>'</SAMP> +<DT><SAMP>‘--switch=<VAR>total-switch-statements</VAR>’</SAMP> <DD> <A NAME="IDX37"></A> Generate 1 or more C <CODE>switch</CODE> statement rather than use a large, @@ -642,8 +644,8 @@ code. </DL> <P> -If the <SAMP>`-t'</SAMP> and <SAMP>`-S'</SAMP> options (or, equivalently, the -<SAMP>`%struct-type'</SAMP> and <SAMP>`%switch'</SAMP> declarations) are omitted, the default +If the <SAMP>‘-t’</SAMP> and <SAMP>‘-S’</SAMP> options (or, equivalently, the +<SAMP>‘%struct-type’</SAMP> and <SAMP>‘%switch’</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 @@ -654,7 +656,7 @@ set characteristics. </P> -<H2><A NAME="SEC17" HREF="gperf_toc.html#TOC17">3.3 Use of NUL bytes</A></H2> +<H2><A NAME="SEC15" HREF="gperf_toc.html#TOC15">4.3 Use of NUL bytes</A></H2> <P> <A NAME="IDX38"></A> @@ -668,7 +670,7 @@ must be NUL terminated and have exactly length <VAR>len</VAR>. </P> <P> -If option <SAMP>`-c'</SAMP> (or, equivalently, the <SAMP>`%compare-strncmp'</SAMP> +If option <SAMP>‘-c’</SAMP> (or, equivalently, the <SAMP>‘%compare-strncmp’</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>. @@ -677,13 +679,39 @@ bytes. </P> <P> -If option <SAMP>`-l'</SAMP> (or, equivalently, the <SAMP>`%compare-lengths'</SAMP> +If option <SAMP>‘-l’</SAMP> (or, equivalently, the <SAMP>‘%compare-lengths’</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>`-c'</SAMP> option (or, equivalently, the -<SAMP>`%compare-strncmp'</SAMP> declaration) is ignored. +Also, in this case the <SAMP>‘-c’</SAMP> option (or, equivalently, the +<SAMP>‘%compare-strncmp’</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> |