.\" -*-nroff-*-
.\"
.\" Manual for CRC23 calculator
.\"
.\" (c) 1999--2001, 2003, 2005, 2009, 2024 Straylight/Edgeware
.\"
.
.\"----- Licensing notice ---------------------------------------------------
.\"
.\" This file is part of the mLib utilities library.
.\"
.\" mLib is free software: you can redistribute it and/or modify it under
.\" the terms of the GNU Library General Public License as published by
.\" the Free Software Foundation; either version 2 of the License, or (at
.\" your option) any later version.
.\"
.\" mLib is distributed in the hope that it will be useful, but WITHOUT
.\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
.\" FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Library General Public
.\" License for more details.
.\"
.\" You should have received a copy of the GNU Library General Public
.\" License along with mLib.  If not, write to the Free Software
.\" Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307,
.\" USA.
.
.\"--------------------------------------------------------------------------
.so ../defs.man \" @@@PRE@@@
.
.\"--------------------------------------------------------------------------
.TH crc32 3mLib "8 May 1999" "Straylight/Edgeware" "mLib utilities library"
.\" @crc32
.
.\"--------------------------------------------------------------------------
.SH NAME
crc32 \- calculate 32-bit CRC
.
.\"--------------------------------------------------------------------------
.SH SYNOPSIS
.
.nf
.B "#include <mLib/crc32.h>"
.PP
.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>
.
.\"----- That's all, folks --------------------------------------------------