@@@ much mess, mostly manpages

[mLib] / hash / unihash-mkstatic.1.in

.\" nroff
.\"
.\" Manual for universal hashing table generator
.\"
.\" (c) 2003, 2005, 2007, 2009, 2019, 2024 Straylight/Edgeware
.\"
.
.\"----- Licensing notice ---------------------------------------------------
.\"
.\" This file is part of the mLib utilities library.
.\"
.\" mLib is free software: you can redistribute it and/or modify it under
.\" the terms of the GNU Library General Public License as published by
.\" the Free Software Foundation; either version 2 of the License, or (at
.\" your option) any later version.
.\"
.\" mLib is distributed in the hope that it will be useful, but WITHOUT
.\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
.\" FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Library General Public
.\" License for more details.
.\"
.\" You should have received a copy of the GNU Library General Public
.\" License along with mLib.  If not, write to the Free Software
.\" Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307,
.\" USA.
.
.\"--------------------------------------------------------------------------
.so ../defs.man \" @@@PRE@@@
.
.\"--------------------------------------------------------------------------
.TH unihash-mkstatic 1 "14 December 2003" "Straylight/Edgeware" "mLib utilities library"
.
.\"--------------------------------------------------------------------------
.SH NAME
unihash-mkstatic \- construct tables for universal hashing
.
.\"--------------------------------------------------------------------------
.SH SYNOPSIS
.
.B unihash-mkstatic
.RB [ \-Cc ]
.RB [ \-s
.IR symbol ]
.RB [ \-i
.IR header ]
.RB [ \-g
.IR macro ]
.br
	\c
.RB [ \-k
.IR key ]
.RB [ \-o
.IR filename ]
.
.\"--------------------------------------------------------------------------
.SH DESCRIPTION
.
The
.B unihash-mkstatic
program constructs tables for efficient universal hashing (see
.BR unihash (3)).
It will produce the table as either an array defined in a C source file
or as an initializer macro defined in a C header file.
.
.SS "Options"
The program accepts no non-option arguments.  The options are as
follows.
.TP
.B "\-h, \-\-help"
Print a help message to standard output and exit successfully.
.TP
.B "\-v, \-\-version"
Print the program's version number to standard output and exit
successfully.
.TP
.B "\-u, \-\-usage"
Print a one-line usage summary to standard output and exit successfully.
.TP
.B "\-C, \-\-const"
When producing C source (the
.B \-c
option), rather than a header, define the table to be
.BR const .
.TP
.B "\-c, \-\-c-source"
Produce a C source file which exports a symbol naming the array, instead
of a C header file.
.TP
.BI "\-s, \-\-symbol=" symbol
Name the table
.IR symbol .
This is the name of the macro defined by a header file, or the array
exported by a C source.  The default macro name is
.BR UHI_INIT ;
the default array name is
.BR uhi .
.TP
.BI "\-i, \-\-include=" header
.RS
Request that generated C source include the named
.I header
file.  Inserts a
line of the form
.IP
.BI "#include """ header """"
.PP
at the top of the generated C source.  The default is not to include
.BR <mLib/unihash.h> ,
which is necessary to declare the
.B unihash_info
type.  This option does nothing without the
.B \-c
option.
.RE
.TP
.BI "\-g, \-\-guard=" macro
.RS
Use the named
.I macro
as a guard against multiple inclusion of the generated header file.
Inserts a pair of lines of the form
.IP
.nf
.BI "#ifndef " macro
.BI "#define " macro
.fi
.PP
at the top of the generated header, and a line
.IP
.BI "#endif"
.PP
at the end.  The default guard macro name is built from the output file
name specified with
.B \-o
by uppercasing all alphabetic characters in the name and replacing
nonalphanumeric characters by underscores
.RB ` _ '.
This option does nothing with the
.B \-c
option.
.RE
.TP
.BI "\-k, \-\-key=" key
Specifies the hashing key as an integer.  Note that if you want to
specify the key in hexadecimal, you must prefix it with
.BR 0x .
The default key is
.BR 0xe07e5bd1 ,
which is, as far as the author knows, as good as any other fixed value.
.
.\"--------------------------------------------------------------------------
.SH "SEE ALSO"
.
.BR crc-mktab (1),
.BR unihash (3).
.
.\"--------------------------------------------------------------------------
.SH "AUTHOR"
.
Mark Wooding, <mdw@distorted.org.uk>
.
.\"----- That's all, folks --------------------------------------------------