chiark - git - mdw - mLib/blob - hash/unihash-mkstatic.1.in

   1 .\" nroff
   2 .\"
   3 .\" Manual for universal hashing table generator
   4 .\"
   5 .\" (c) 2003, 2005, 2007, 2009, 2019, 2024 Straylight/Edgeware
   6 .\"
   7 .
   8 .\"----- Licensing notice ---------------------------------------------------
   9 .\"
  10 .\" This file is part of the mLib utilities library.
  11 .\"
  12 .\" mLib is free software: you can redistribute it and/or modify it under
  13 .\" the terms of the GNU Library General Public License as published by
  14 .\" the Free Software Foundation; either version 2 of the License, or (at
  15 .\" your option) any later version.
  16 .\"
  17 .\" mLib is distributed in the hope that it will be useful, but WITHOUT
  18 .\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  19 .\" FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Library General Public
  20 .\" License for more details.
  21 .\"
  22 .\" You should have received a copy of the GNU Library General Public
  23 .\" License along with mLib.  If not, write to the Free Software
  24 .\" Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307,
  25 .\" USA.
  26 .
  27 .\"--------------------------------------------------------------------------
  28 .so ../defs.man \" @@@PRE@@@
  29 .
  30 .\"--------------------------------------------------------------------------
  31 .TH unihash-mkstatic 1 "14 December 2003" "Straylight/Edgeware" "mLib utilities library"
  32 .
  33 .\"--------------------------------------------------------------------------
  34 .SH NAME
  35 unihash-mkstatic \- construct tables for universal hashing
  36 .
  37 .\"--------------------------------------------------------------------------
  38 .SH SYNOPSIS
  39 .
  40 .B unihash-mkstatic
  41 .RB [ \-Cc ]
  42 .RB [ \-s
  43 .IR symbol ]
  44 .RB [ \-i
  45 .IR header ]
  46 .RB [ \-g
  47 .IR macro ]
  48 .br
  49         \c
  50 .RB [ \-k
  51 .IR key ]
  52 .RB [ \-o
  53 .IR filename ]
  54 .
  55 .\"--------------------------------------------------------------------------
  56 .SH DESCRIPTION
  57 .
  58 The
  59 .B unihash-mkstatic
  60 program constructs tables for efficient universal hashing (see
  61 .BR unihash (3)).
  62 It will produce the table as either an array defined in a C source file
  63 or as an initializer macro defined in a C header file.
  64 .
  65 .SS "Options"
  66 The program accepts no non-option arguments.  The options are as
  67 follows.
  68 .TP
  69 .B "\-h, \-\-help"
  70 Print a help message to standard output and exit successfully.
  71 .TP
  72 .B "\-v, \-\-version"
  73 Print the program's version number to standard output and exit
  74 successfully.
  75 .TP
  76 .B "\-u, \-\-usage"
  77 Print a one-line usage summary to standard output and exit successfully.
  78 .TP
  79 .B "\-C, \-\-const"
  80 When producing C source (the
  81 .B \-c
  82 option), rather than a header, define the table to be
  83 .BR const .
  84 .TP
  85 .B "\-c, \-\-c-source"
  86 Produce a C source file which exports a symbol naming the array, instead
  87 of a C header file.
  88 .TP
  89 .BI "\-s, \-\-symbol=" symbol
  90 Name the table
  91 .IR symbol .
  92 This is the name of the macro defined by a header file, or the array
  93 exported by a C source.  The default macro name is
  94 .BR UHI_INIT ;
  95 the default array name is
  96 .BR uhi .
  97 .TP
  98 .BI "\-i, \-\-include=" header
  99 .RS
 100 Request that generated C source include the named
 101 .I header
 102 file.  Inserts a
 103 line of the form
 104 .IP
 105 .BI "#include """ header """"
 106 .PP
 107 at the top of the generated C source.  The default is not to include
 108 .BR <mLib/unihash.h> ,
 109 which is necessary to declare the
 110 .B unihash_info
 111 type.  This option does nothing without the
 112 .B \-c
 113 option.
 114 .RE
 115 .TP
 116 .BI "\-g, \-\-guard=" macro
 117 .RS
 118 Use the named
 119 .I macro
 120 as a guard against multiple inclusion of the generated header file.
 121 Inserts a pair of lines of the form
 122 .IP
 123 .nf
 124 .BI "#ifndef " macro
 125 .BI "#define " macro
 126 .fi
 127 .PP
 128 at the top of the generated header, and a line
 129 .IP
 130 .BI "#endif"
 131 .PP
 132 at the end.  The default guard macro name is built from the output file
 133 name specified with
 134 .B \-o
 135 by uppercasing all alphabetic characters in the name and replacing
 136 nonalphanumeric characters by underscores
 137 .RB ` _ '.
 138 This option does nothing with the
 139 .B \-c
 140 option.
 141 .RE
 142 .TP
 143 .BI "\-k, \-\-key=" key
 144 Specifies the hashing key as an integer.  Note that if you want to
 145 specify the key in hexadecimal, you must prefix it with
 146 .BR 0x .
 147 The default key is
 148 .BR 0xe07e5bd1 ,
 149 which is, as far as the author knows, as good as any other fixed value.
 150 .
 151 .\"--------------------------------------------------------------------------
 152 .SH "SEE ALSO"
 153 .
 154 .BR crc-mktab (1),
 155 .BR unihash (3).
 156 .
 157 .\"--------------------------------------------------------------------------
 158 .SH "AUTHOR"
 159 .
 160 Mark Wooding, <mdw@distorted.org.uk>
 161 .
 162 .\"----- That's all, folks --------------------------------------------------