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