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

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