[mLib] / hash / crc-mktab.1

.\" nroff
.ie t \{\
.  ds ss \s8\u
.  ds se \d\s0
.\}
.el \{\
.  ds ss ^
.  ds se
.\}
.TH crc-mktab 1 "9 November 2003" "Straylight/Edgeware" "mLib utilities library"
.SH NAME
crc-mktab \- construct CRC tables for efficient computation
.SH SYNOPSIS
.B crc-mktab
.RB [ \-Ccr ]
.RB [ \-s
.IR symbol ]
.RB [ \-t
.IR type ]
.RB [ \-i
.IR header ]
.br
	\c
.RB [ \-g
.IR macro ]
.RB [ \-b
.IR bits ]
.RB [ \-B
.IR chunk ]
.RB [ \-p
.IR poly ]
.br
	\c
.RB [ \-o
.IR filename ]
.SH DESCRIPTION
The
.B crc-mktab
program constructs tables for efficient computation of CRC (cyclic
redundancy check) values.  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.  At least one of
.B \-b
or
.B \-p
must be given.  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 .
.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 CRC_TAB ;
the default array name is
.BR crctab .
.TP
.BI "\-t, \-\-type=" type
Specify the element type of the array defined by a C source output.  The
default is
.B "unsigned short"
if the polynomial has degree 16 or less, or
.B "unsigned long"
otherwise.  This option does nothing without the
.B \-c
option.
.TP
.BI "\-i, \-\-include=" header
Request that generated C source include the named
.I header
file.  Inserts a
line of the form
.PP
.nf
.BI "          #include """ header """"
.fi
.IP
at the top of the generated C source.  The default is not to include a
header file.  This option does nothing without the
.B \-c
option.
.TP
.BI "\-g, \-\-guard=" macro
Use the named
.I macro
as a guard against multiple inclusion of the generated header file.
Inserts a pair of lines of the form
.PP
.nf
.BI "          #ifndef " macro
.BI "          #define " macro
.fi
.IP
at the top of the generated header, and a line
.PP
.nf
.BI "          #endif"
.fi
.IP
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.
.TP
.BI "\-b, \-\-bits=" bits
Specifies the degree of the CRC polynomial or, equivalently, the length
of the generated CRC.  This must be an integer between 1 and 32
inclusive.  If it is not specified, the polynomial given by
.B \-p
is examined and an educated guess made.  (Currently we choose the
smallest multiple of 8 which is large enough.)
.TP
.BI "\-B, \-\-bit-chunk=" chunk
Chunk size in which bits are taken from the input.  The number of
entries in the table is precisely
.RI 2\*(ss chunk \*(se.
The default chunk size is 8.
.TP
.BI "\-p, \-\-polynomial=" poly
Specifies the CRC polynomial as an integer.  The polynomial has a
nonzero coefficient in its
.IR x \*(ss i \*(se
term if and only if bit
.I i
of
.I poly
is nonzero.  Note that if you want to specify the polynomial in
hexadecimal, you must prefix it with
.BR 0x .
Default polynomials of degree 16 and 32 are known.
.TP
.B "\-r, \-\-reverse"
Construct the table to compensate for unusual bit-ordering.  Without
this option, you'd have to reverse the order of all input chunks and the
output CRC.
.SS "The table and how to use it"
Describing in detail the contents of the table would take too long.  For
an example of use, see the header file
.BR crc32.h .
.SH "SEE ALSO"
.BR crc32 (3).
.PP
.I A painless guide to CRC error detection algorithms
by Ross N. Williams.
.SH "AUTHOR"
Mark Wooding, <mdw@distorted.org.uk>
Commit	Line	Data
7c14e955	1	.\" nroff
	2	.ie t \{\
	3	. ds ss \s8\u
	4	. ds se \d\s0
	5	.\}
	6	.el \{\
	7	. ds ss ^
	8	. ds se
	9	.\}
	10	.TH crc-mktab 1 "9 November 2003" "Straylight/Edgeware" "mLib utilities library"
	11	.SH NAME
	12	crc-mktab \- construct CRC tables for efficient computation
	13	.SH SYNOPSIS
	14	.B crc-mktab
3e7267bf	15	.RB [ \-Ccr ]
7c14e955	16	.RB [ \-s
	17	.IR symbol ]
	18	.RB [ \-t
	19	.IR type ]
	20	.RB [ \-i
	21	.IR header ]
	22	.br
	23	\c
	24	.RB [ \-g
	25	.IR macro ]
	26	.RB [ \-b
	27	.IR bits ]
	28	.RB [ \-B
	29	.IR chunk ]
	30	.RB [ \-p
	31	.IR poly ]
	32	.br
	33	\c
	34	.RB [ \-o
	35	.IR filename ]
	36	.SH DESCRIPTION
	37	The
	38	.B crc-mktab
	39	program constructs tables for efficient computation of CRC (cyclic
	40	redundancy check) values. It will produce the table as either an array
	41	defined in a C source file or as an initializer macro defined in a C
	42	header file.
	43	.SS "Options"
	44	The program accepts no non-option arguments. At least one of
	45	.B \-b
	46	or
	47	.B \-p
	48	must be given. The options are as follows.
	49	.TP
	50	.B "\-h, \-\-help"
	51	Print a help message to standard output and exit successfully.
	52	.TP
	53	.B "\-v, \-\-version"
	54	Print the program's version number to standard output and exit
	55	successfully.
	56	.TP
	57	.B "\-u, \-\-usage"
	58	Print a one-line usage summary to standard output and exit successfully.
	59	.TP
3e7267bf MW	60	.B "\-C, \-\-const"
	61	When producing C source (the
	62	.B \-c
	63	option), rather than a header, define the table to be
	64	.BR const .
7c14e955	65	.B "\-c, \-\-c-source"
	66	Produce a C source file which exports a symbol naming the array, instead
	67	of a C header file.
	68	.TP
6f444bda	69	.BI "\-s, \-\-symbol=" symbol
7c14e955	70	Name the table
	71	.IR symbol .
	72	This is the name of the macro defined by a header file, or the array
	73	exported by a C source. The default macro name is
	74	.BR CRC_TAB ;
	75	the default array name is
	76	.BR crctab .
	77	.TP
	78	.BI "\-t, \-\-type=" type
	79	Specify the element type of the array defined by a C source output. The
d4efbcd9	80	default is
7c14e955	81	.B "unsigned short"
	82	if the polynomial has degree 16 or less, or
	83	.B "unsigned long"
	84	otherwise. This option does nothing without the
	85	.B \-c
	86	option.
	87	.TP
	88	.BI "\-i, \-\-include=" header
d4efbcd9	89	Request that generated C source include the named
7c14e955	90	.I header
	91	file. Inserts a
	92	line of the form
	93	.PP
	94	.nf
	95	.BI " #include """ header """"
	96	.fi
	97	.IP
	98	at the top of the generated C source. The default is not to include a
	99	header file. This option does nothing without the
	100	.B \-c
	101	option.
	102	.TP
	103	.BI "\-g, \-\-guard=" macro
	104	Use the named
	105	.I macro
	106	as a guard against multiple inclusion of the generated header file.
	107	Inserts a pair of lines of the form
	108	.PP
	109	.nf
	110	.BI " #ifndef " macro
	111	.BI " #define " macro
	112	.fi
	113	.IP
	114	at the top of the generated header, and a line
	115	.PP
	116	.nf
	117	.BI " #endif"
	118	.fi
	119	.IP
	120	at the end. The default guard macro name is built from the output file
	121	name specified with
	122	.B \-o
	123	by uppercasing all alphabetic characters in the name and replacing
d4efbcd9	124	nonalphanumeric characters by underscores
7c14e955	125	.RB ` _ '.
	126	This option does nothing with the
	127	.B \-c
	128	option.
	129	.TP
	130	.BI "\-b, \-\-bits=" bits
	131	Specifies the degree of the CRC polynomial or, equivalently, the length
	132	of the generated CRC. This must be an integer between 1 and 32
	133	inclusive. If it is not specified, the polynomial given by
	134	.B \-p
	135	is examined and an educated guess made. (Currently we choose the
	136	smallest multiple of 8 which is large enough.)
	137	.TP
	138	.BI "\-B, \-\-bit-chunk=" chunk
	139	Chunk size in which bits are taken from the input. The number of
	140	entries in the table is precisely
	141	.RI 2\(ss chunk \(se.
	142	The default chunk size is 8.
	143	.TP
	144	.BI "\-p, \-\-polynomial=" poly
	145	Specifies the CRC polynomial as an integer. The polynomial has a
	146	nonzero coefficient in its
	147	.IR x \(ss i \(se
	148	term if and only if bit
	149	.I i
	150	of
	151	.I poly
	152	is nonzero. Note that if you want to specify the polynomial in
	153	hexadecimal, you must prefix it with
	154	.BR 0x .
	155	Default polynomials of degree 16 and 32 are known.
	156	.TP
	157	.B "\-r, \-\-reverse"
	158	Construct the table to compensate for unusual bit-ordering. Without
	159	this option, you'd have to reverse the order of all input chunks and the
	160	output CRC.
	161	.SS "The table and how to use it"
	162	Describing in detail the contents of the table would take too long. For
	163	an example of use, see the header file
	164	.BR crc32.h .
	165	.SH "SEE ALSO"
	166	.BR crc32 (3).
	167	.PP
	168	.I A painless guide to CRC error detection algorithms
	169	by Ross N. Williams.
	170	.SH "AUTHOR"
9b5ac6ff	171	Mark Wooding, <mdw@distorted.org.uk>
7c14e955	172