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

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