chiark - git - mdw - mLib/blob - 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