PROLOG This manual page is part of the POSIX Programmer
s Manual. The Linux implementation of this interface may
differ (consult the corresponding Linux manual page for
details of Linux behavior), or the interface may not be
implemented on Linux.

NAME cksum - write file checksums and sizes

SYNOPSIS cksum [file ...]

DESCRIPTION The cksum utility shall calculate and write
to standard output a cyclic redundancy check (CRC) for each
input file, and also write to standard output the number of
octets in each file. The CRC used is based on the polynomial
used for CRC error checking in the ISO/IEC 8802-3:1996 stan-
dard (Ethernet).

The encoding for the CRC checksum is defined by the
generating polyno- mial:

Mathematically, the CRC value corresponding to a given
file shall be defined by the following procedure:

1. The n bits to be evaluated are considered to be the
coefficients of a mod 2 polynomial M( x) of degree n-1.
These n bits are the bits from the file, with the most
significant bit being the most signif- icant bit of the
first octet of the file and the last bit being the least
significant bit of the last octet, padded with zero bits (if
necessary) to achieve an integral number of octets, followed
by one or more octets representing the length of the file as
a binary value, least significant octet first. The smallest
number of octets capable of representing this integer shall
be used.

file A pathname of a file to be checked. If no file
operands are specified, the standard input shall be
used.

STDIN The standard input shall be used only if no file
operands are speci- fied. See the INPUT FILES section.

INPUT FILES The input files can be any file type.

ENVIRONMENT VARIABLES The following environment
variables shall affect the execution of cksum:

LANG Provide a default value for the
internationalization variables that are unset or null. (See
the Base Definitions volume of IEEE Std 1003.1-2001, Section
8.2, Internationalization Vari- ables for the precedence of
internationalization variables used to determine the values
of locale categories.)

LC_ALL If set to a non-empty string value, override the
values of all the other internationalization variables.

LC_CTYPE Determine the locale for the interpretation of
sequences of bytes of text data as characters (for example,
single-byte as opposed to multi-byte characters in
arguments).

LC_MESSAGES Determine the locale that should be used to
affect the format and contents of diagnostic messages
written to standard error.

NLSPATH Determine the location of message catalogs for
the processing of LC_MESSAGES .

ASYNCHRONOUS EVENTS Default.

STDOUT For each file processed successfully, the cksum
utility shall write in the following format:

"%u %d %n", <checksum>, <# of
octets>, <pathname>

If no file operand was specified, the pathname and its
leading <space> shall be omitted.

STDERR The standard error shall be used only for
diagnostic messages.

OUTPUT FILES None.

EXTENDED DESCRIPTION None.

EXIT STATUS The following exit values shall be
returned:

0 All files were processed successfully.

>0 An error occurred.

CONSEQUENCES OF ERRORS Default.

The following sections are informative.

APPLICATION USAGE The cksum utility is typically used to
quickly compare a suspect file against a trusted version of
the same, such as to ensure that files transmitted over
noisy media arrive intact. However, this comparison cannot
be considered cryptographically secure. The chances of a
damaged file producing the same CRC as the original are
small; deliberate deception is difficult, but probably not
impossible.

Although input files to cksum can be any type, the
results need not be what would be expected on character
special device files or on file types not described by the
System Interfaces volume of IEEE Std 1003.1-2001. Since this
volume of IEEE Std 1003.1-2001 does not specify the block
size used when doing input, checksums of charac- ter special
files need not process all of the data in those files.

The algorithm is expressed in terms of a bitstream
divided into octets. If a file is transmitted between two
systems and undergoes any data transformation (such as
changing little-endian byte ordering to big- endian),
identical CRC values cannot be expected. Implementations
per- forming such transformations may extend cksum to handle
such situa- tions.

EXAMPLES None.

RATIONALE The following C-language program can be used
as a model to describe the algorithm. It assumes that a char
is one octet. It also assumes that the entire file is
available for one pass through the function. This was done
for simplicity in demonstrating the algorithm, rather than
as an implementation model.

The historical practice of writing the number of
"blocks" has been changed to writing the number of
octets, since the latter is not only more useful, but also
since historical implementations have not been consistent in
defining what a "block" meant. Octets are used
instead of bytes because bytes can differ in size between
systems.

The algorithm used was selected to increase the
operational robustness of cksum. Neither the System V nor
BSD sum algorithm was selected. Since each of these was
different and each was the default behavior on those
systems, no realistic compromise was available if either
were selected-some set of historical applications would
break. Therefore, the name was changed to cksum. Although
the historical sum commands will probably continue to be
provided for many years, programs designed for portability
across systems should use the new name.

The algorithm selected is based on that used by the
ISO/IEC 8802-3:1996 standard (Ethernet) for the frame check
sequence field. The algorithm used does not match the
technical definition of a checksum; the term is used for
historical reasons. The length of the file is included in
the CRC calculation because this parallels inclusion of a
length field by Ethernet in its CRC, but also because it
guards against inadvertent collisions between files that
begin with different series of zero octets. The chance that
two different files produce identical CRCs is much greater
when their lengths are not considered. Keeping the length
and the checksum of the file itself separate would yield a
slightly more robust algorithm, but historical usage has
always been that a sin- gle number (the checksum as printed)
represents the signature of the file. It was decided that
historical usage was the more important con- sideration.

Early proposals contained modifications to the Ethernet
algorithm that involved extracting table values whenever an
intermediate result became zero. This was demonstrated to be
less robust than the current method and mathematically
difficult to describe or justify.

The calculation used is identical to that given in
pseudo-code in the referenced Sarwate article. The
pseudo-code rendition is:

The pseudo-code is reproduced exactly as given; however,
note that in the case of cksum, A[i] represents a byte of
the file, the words X and Y are treated as a single 32-bit
value, and the tables f and fare a single table containing
32-bit values.

The referenced Sarwate article also discusses generating
the table.

FUTURE DIRECTIONS None.

SEE ALSO None.

COPYRIGHT Portions of this text are reprinted and
reproduced in electronic form from IEEE Std 1003.1, 2003
Edition, Standard for Information Technology -- Portable
Operating System Interface (POSIX), The Open Group Base
Specifications Issue 6, Copyright (C) 2001-2003 by the
Institute of Electrical and Electronics Engineers, Inc and
The Open Group. In the event of any discrepancy between this
version and the original IEEE and The Open Group Standard,
the original IEEE and The Open Group Standard is the referee
document. The original Standard can be obtained online at
http://www.opengroup.org/unix/online.html .