Headers: Guard inclusion of mLib headers.

[mLib] / crc32.3

.\" -*-nroff-*-
.ie t \{\
.  ds ss \s8\u
.  ds se \d\s0
.\}
.el \{\
.  ds ss ^
.  ds se
.\}
.TH crc32 3 "8 May 1999" "Straylight/Edgeware" "mLib utilities library"
.SH NAME
crc32 \- calculate 32-bit CRC
.\" @crc32
.SH SYNOPSIS
.nf
.B "#include <mLib/crc32.h>"

.BI "uint32 crc32(uint32 " crc ", const void *" buf ", size_t " sz );
.BI CRC32( result ", " crc ", " buf ", " sz )
.fi
.SH DESCRIPTION
The
.B crc32
function calculates a 32-bit cyclic redundancy check of the data block
at address
.I buf
and size
.I sz
passed to it.
.PP
The function is restartable.  For a first call, pass zero as the value
of the
.I crc
argument; for subsequent blocks, pass in the previous output.  The final
answer is equal to the result you'd get from computing a CRC over the
concatenation of the individual blocks.
.PP
The
.B CRC32
macro calculates a CRC inline.  The calculated CRC value is placed in
the variable named by
.IR result .
Only use the macro version when efficiency is a major concern: it makes
the code rather harder to read.
.PP
Note that a CRC is not cryptographically strong: it's fairly easy for an
adversary to construct blocks of data with any desired CRC, or to modify
a given block in a way which doesn't change its (unknown) CRC.
.PP
The exact behaviour of the CRC is beyond the scope of this manual;
suffice to say that the result is, in some suitable representation, the
remainder after division by a degree-32 polynomial in GF(2)[x].
.SH "RETURN VALUE"
The return value is the 32-bit CRC of the input block.
.SH "SEE ALSO"
.BR unihash (3),
.BR mLib (3).
.SH AUTHOR
Mark Wooding, <mdw@distorted.org.uk>