| 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> |