chiark / gitweb /
Import buf from Catacomb; split out the dstr bits, and throw away the mp and
[mLib] / man / crc-mktab.1
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
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
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
60 .B "\-c, \-\-c-source"
61 Produce a C source file which exports a symbol naming the array, instead
62 of a C header file.
63 .TP
64 .BI "\-s, \-\-symbol=" symbol
65 Name the table
66 .IR symbol .
67 This is the name of the macro defined by a header file, or the array
68 exported by a C source.  The default macro name is
69 .BR CRC_TAB ;
70 the default array name is
71 .BR crctab .
72 .TP
73 .BI "\-t, \-\-type=" type
74 Specify the element type of the array defined by a C source output.  The
75 default is 
76 .B "unsigned short"
77 if the polynomial has degree 16 or less, or
78 .B "unsigned long"
79 otherwise.  This option does nothing without the
80 .B \-c
81 option.
82 .TP
83 .BI "\-i, \-\-include=" header
84 Request that generated C source include the named 
85 .I header
86 file.  Inserts a
87 line of the form
88 .PP
89 .nf
90 .BI "          #include """ header """"
91 .fi
92 .IP
93 at the top of the generated C source.  The default is not to include a
94 header file.  This option does nothing without the
95 .B \-c
96 option.
97 .TP
98 .BI "\-g, \-\-guard=" macro
99 Use the named
100 .I macro
101 as a guard against multiple inclusion of the generated header file.
102 Inserts a pair of lines of the form
103 .PP
104 .nf
105 .BI "          #ifndef " macro
106 .BI "          #define " macro
107 .fi
108 .IP
109 at the top of the generated header, and a line
110 .PP
111 .nf
112 .BI "          #endif"
113 .fi
114 .IP
115 at the end.  The default guard macro name is built from the output file
116 name specified with
117 .B \-o
118 by uppercasing all alphabetic characters in the name and replacing
119 nonalphanumeric characters by underscores 
120 .RB ` _ '.
121 This option does nothing with the
122 .B \-c
123 option.
124 .TP
125 .BI "\-b, \-\-bits=" bits
126 Specifies the degree of the CRC polynomial or, equivalently, the length
127 of the generated CRC.  This must be an integer between 1 and 32
128 inclusive.  If it is not specified, the polynomial given by
129 .B \-p
130 is examined and an educated guess made.  (Currently we choose the
131 smallest multiple of 8 which is large enough.)
132 .TP
133 .BI "\-B, \-\-bit-chunk=" chunk
134 Chunk size in which bits are taken from the input.  The number of
135 entries in the table is precisely
136 .RI 2\*(ss chunk \*(se.
137 The default chunk size is 8.
138 .TP
139 .BI "\-p, \-\-polynomial=" poly
140 Specifies the CRC polynomial as an integer.  The polynomial has a
141 nonzero coefficient in its
142 .IR x \*(ss i \*(se
143 term if and only if bit
144 .I i
145 of
146 .I poly
147 is nonzero.  Note that if you want to specify the polynomial in
148 hexadecimal, you must prefix it with
149 .BR 0x .
150 Default polynomials of degree 16 and 32 are known.
151 .TP
152 .B "\-r, \-\-reverse"
153 Construct the table to compensate for unusual bit-ordering.  Without
154 this option, you'd have to reverse the order of all input chunks and the
155 output CRC.
156 .SS "The table and how to use it"
157 Describing in detail the contents of the table would take too long.  For
158 an 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
164 by Ross N. Williams.
165 .SH "AUTHOR"
166 Mark Wooding, <mdw@distorted.org.uk>
167