chiark - git - mdw - mLib/blob - man/crc32.3

   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 crc32 3 "8 May 1999" "mLib"
  11 .SH NAME
  12 crc32 \- calculate 32-bit CRC
  13 .\" @crc32
  14 .SH SYNOPSIS
  15 .nf
  16 .B "#include <mLib/crc32.h>"
  17
  18 .BI "uint32 crc32(uint32 " crc ", const void *" buf ", size_t " sz );
  19 .BI CRC32( result ", " crc ", " buf ", " sz )
  20 .fi
  21 .SH DESCRIPTION
  22 The
  23 .B crc32
  24 function calculates a 32-bit cyclic redundancy check of the data block
  25 at address
  26 .I buf
  27 and size
  28 .I sz
  29 passed to it.
  30 .PP
  31 The function is restartable.  For a first call, pass zero as the value
  32 of the
  33 .I crc
  34 argument; for subsequent blocks, pass in the previous output.  The final
  35 answer is equal to the result you'd get from computing a CRC over the
  36 concatenation of the individual blocks.
  37 .PP
  38 The
  39 .B CRC32
  40 macro calculates a CRC inline.  The calculated CRC value is placed in
  41 the variable named by
  42 .IR result .
  43 Only use the macro version when efficiency is a major concern: it makes
  44 the code rather harder to read.
  45 .PP
  46 Note that a CRC is not cryptographically strong: it's fairly easy for an
  47 adversary to construct blocks of data with any desired CRC, or to modify
  48 a given block in a way which doesn't change its (unknown) CRC.
  49 .PP
  50 The exact behaviour of the CRC is beyond the scope of this manual;
  51 suffice to say that the result is, in some suitable representation, the
  52 remainder after division in the finite field GF(2\*(ss32\*(se) of the
  53 block by a carefully chosen polynomial of order 32.
  54 .SH "RETURN VALUE"
  55 The return value is the 32-bit CRC of the input block.
  56 .SH "SEE ALSO"
  57 .BR mLib (3).
  58 .SH AUTHOR
  59 Mark Wooding, <mdw@nsict.org>