chiark - git - mdw - mLib/blob - hash/crc-mktab.1.in

   1 .\" nroff
   2 .\"
   3 .\" Manual for CRC table generator
   4 .\"
   5 .\" (c) 2003, 2005, 2007, 2009, 2019, 2024 Straylight/Edgeware
   6 .\"
   7 .
   8 .\"----- Licensing notice ---------------------------------------------------
   9 .\"
  10 .\" This file is part of the mLib utilities library.
  11 .\"
  12 .\" mLib is free software: you can redistribute it and/or modify it under
  13 .\" the terms of the GNU Library General Public License as published by
  14 .\" the Free Software Foundation; either version 2 of the License, or (at
  15 .\" your option) any later version.
  16 .\"
  17 .\" mLib is distributed in the hope that it will be useful, but WITHOUT
  18 .\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  19 .\" FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Library General Public
  20 .\" License for more details.
  21 .\"
  22 .\" You should have received a copy of the GNU Library General Public
  23 .\" License along with mLib.  If not, write to the Free Software
  24 .\" Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307,
  25 .\" USA.
  26 .
  27 .\"--------------------------------------------------------------------------
  28 .so ../defs.man \" @@@PRE@@@
  29 .
  30 .\"--------------------------------------------------------------------------
  31 .TH crc-mktab 1 "9 November 2003" "Straylight/Edgeware" "mLib utilities library"
  32 .
  33 .\"--------------------------------------------------------------------------
  34 .SH NAME
  35 crc-mktab \- construct CRC tables for efficient computation
  36 .
  37 .\"--------------------------------------------------------------------------
  38 .SH SYNOPSIS
  39 .
  40 .B crc-mktab
  41 .RB [ \-Ccr ]
  42 .RB [ \-s
  43 .IR symbol ]
  44 .RB [ \-t
  45 .IR type ]
  46 .RB [ \-i
  47 .IR header ]
  48 .br
  49         \c
  50 .RB [ \-g
  51 .IR macro ]
  52 .RB [ \-b
  53 .IR bits ]
  54 .RB [ \-B
  55 .IR chunk ]
  56 .RB [ \-p
  57 .IR poly ]
  58 .br
  59         \c
  60 .RB [ \-o
  61 .IR filename ]
  62 .
  63 .\"--------------------------------------------------------------------------
  64 .SH DESCRIPTION
  65 .
  66 The
  67 .B crc-mktab
  68 program constructs tables for efficient computation of CRC (cyclic
  69 redundancy check) values.  It will produce the table as either an array
  70 defined in a C source file or as an initializer macro defined in a C
  71 header file.
  72 .SS "Options"
  73 The program accepts no non-option arguments.  At least one of
  74 .B \-b
  75 or
  76 .B \-p
  77 must be given.  The options are as follows.
  78 .TP
  79 .B "\-h, \-\-help"
  80 Print a help message to standard output and exit successfully.
  81 .TP
  82 .B "\-v, \-\-version"
  83 Print the program's version number to standard output and exit
  84 successfully.
  85 .TP
  86 .B "\-u, \-\-usage"
  87 Print a one-line usage summary to standard output and exit successfully.
  88 .TP
  89 .B "\-C, \-\-const"
  90 When producing C source (the
  91 .B \-c
  92 option), rather than a header, define the table to be
  93 .BR const .
  94 .B "\-c, \-\-c-source"
  95 Produce a C source file which exports a symbol naming the array, instead
  96 of a C header file.
  97 .TP
  98 .BI "\-s, \-\-symbol=" symbol
  99 Name the table
 100 .IR symbol .
 101 This is the name of the macro defined by a header file, or the array
 102 exported by a C source.  The default macro name is
 103 .BR CRC_TAB ;
 104 the default array name is
 105 .BR crctab .
 106 .TP
 107 .BI "\-t, \-\-type=" type
 108 Specify the element type of the array defined by a C source output.  The
 109 default is
 110 .B "unsigned short"
 111 if the polynomial has degree 16 or less, or
 112 .B "unsigned long"
 113 otherwise.  This option does nothing without the
 114 .B \-c
 115 option.
 116 .TP
 117 .BI "\-i, \-\-include=" header
 118 .RS
 119 Request that generated C source include the named
 120 .I header
 121 file.  Inserts a
 122 line of the form
 123 .IP
 124 .BI "#include """ header """"
 125 .PP
 126 at the top of the generated C source.  The default is not to include a
 127 header file.  This option does nothing without the
 128 .B \-c
 129 option.
 130 .RE
 131 .TP
 132 .BI "\-g, \-\-guard=" macro
 133 .RS
 134 Use the named
 135 .I macro
 136 as a guard against multiple inclusion of the generated header file.
 137 Inserts a pair of lines of the form
 138 .IP
 139 .nf
 140 .BI "#ifndef " macro
 141 .BI "#define " macro
 142 .fi
 143 .PP
 144 at the top of the generated header, and a line
 145 .IP
 146 .BI "#endif"
 147 .PP
 148 at the end.  The default guard macro name is built from the output file
 149 name specified with
 150 .B \-o
 151 by uppercasing all alphabetic characters in the name and replacing
 152 nonalphanumeric characters by underscores
 153 .RB ` _ '.
 154 This option does nothing with the
 155 .B \-c
 156 option.
 157 .RE
 158 .TP
 159 .BI "\-b, \-\-bits=" bits
 160 Specifies the degree of the CRC polynomial or, equivalently, the length
 161 of the generated CRC.  This must be an integer between 1 and 32
 162 inclusive.  If it is not specified, the polynomial given by
 163 .B \-p
 164 is examined and an educated guess made.  (Currently we choose the
 165 smallest multiple of 8 which is large enough.)
 166 .TP
 167 .BI "\-B, \-\-bit-chunk=" chunk
 168 Chunk size in which bits are taken from the input.  The number of
 169 entries in the table is precisely
 170 .RI 2\*(ss chunk \*(se.
 171 The default chunk size is 8.
 172 .TP
 173 .BI "\-p, \-\-polynomial=" poly
 174 Specifies the CRC polynomial as an integer.  The polynomial has a
 175 nonzero coefficient in its
 176 .IR x \*(ss i \*(se
 177 term if and only if bit
 178 .I i
 179 of
 180 .I poly
 181 is nonzero.  Note that if you want to specify the polynomial in
 182 hexadecimal, you must prefix it with
 183 .BR 0x .
 184 Default polynomials of degree 16 and 32 are known.
 185 .TP
 186 .B "\-r, \-\-reverse"
 187 Construct the table to compensate for unusual bit-ordering.  Without
 188 this option, you'd have to reverse the order of all input chunks and the
 189 output CRC.
 190 .SS "The table and how to use it"
 191 Describing in detail the contents of the table would take too long.  For
 192 an example of use, see the header file
 193 .BR crc32.h .
 194 .
 195 .\"--------------------------------------------------------------------------
 196 .SH "SEE ALSO"
 197 .
 198 .BR crc32 (3).
 199 .PP
 200 .I A painless guide to CRC error detection algorithms
 201 by Ross N. Williams.
 202 .
 203 .\"--------------------------------------------------------------------------
 204 .SH "AUTHOR"
 205 .
 206 Mark Wooding, <mdw@distorted.org.uk>
 207 .
 208 .\"----- That's all, folks --------------------------------------------------