mdw@git.distorted.org.uk Git - mLib/blob - hash/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 [ \-Ccr ]
  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, \-\-const"
  61 When producing C source (the
  62 .B \-c
  63 option), rather than a header, define the table to be
  64 .BR const .
  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
  69 .BI "\-s, \-\-symbol=" symbol
  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
  80 default is
  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
  89 Request that generated C source include the named
  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
 124 nonalphanumeric characters by underscores
 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"
 171 Mark Wooding, <mdw@distorted.org.uk>
 172