usr.bin/cksum/cksum.1

   1 .\" Copyright (c) 1991, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" This code is derived from software contributed to Berkeley by
   5 .\" the Institute of Electrical and Electronics Engineers, Inc.
   6 .\"
   7 .\" Redistribution and use in source and binary forms, with or without
   8 .\" modification, are permitted provided that the following conditions
   9 .\" are met:
  10 .\" 1. Redistributions of source code must retain the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer.
  12 .\" 2. Redistributions in binary form must reproduce the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer in the
  14 .\"    documentation and/or other materials provided with the distribution.
  15 .\" 4. Neither the name of the University nor the names of its contributors
  16 .\"    may be used to endorse or promote products derived from this software
  17 .\"    without specific prior written permission.
  18 .\"
  19 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  20 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  21 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  22 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  23 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  24 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  25 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  26 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  27 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  28 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  29 .\" SUCH DAMAGE.
  30 .\"
  31 .\"     @(#)cksum.1     8.2 (Berkeley) 4/28/95
  32 .\" $FreeBSD$
  33 .\"
  34 .Dd April 28, 1995
  35 .Dt CKSUM 1
  36 .Os
  37 .Sh NAME
  38 .Nm cksum ,
  39 .Nm sum
  40 .Nd display file checksums and block counts
  41 .Sh SYNOPSIS
  42 .Nm
  43 .Op Fl o Ar 1 | 2 | 3
  44 .Op Ar
  45 .Nm sum
  46 .Op Ar
  47 .Sh DESCRIPTION
  48 The
  49 .Nm
  50 utility writes to the standard output three whitespace separated
  51 fields for each input file.
  52 These fields are a checksum
  53 .Tn CRC ,
  54 the total number of octets in the file and the file name.
  55 If no file name is specified, the standard input is used and no file name
  56 is written.
  57 .Pp
  58 The
  59 .Nm sum
  60 utility is identical to the
  61 .Nm
  62 utility, except that it defaults to using historic algorithm 1, as
  63 described below.
  64 It is provided for compatibility only.
  65 .Pp
  66 The options are as follows:
  67 .Bl -tag -width indent
  68 .It Fl o
  69 Use historic algorithms instead of the (superior) default one.
  70 .Pp
  71 Algorithm 1 is the algorithm used by historic
  72 .Bx
  73 systems as the
  74 .Xr sum 1
  75 algorithm and by historic
  76 .At V
  77 systems as the
  78 .Xr sum 1
  79 algorithm when using the
  80 .Fl r
  81 option.
  82 This is a 16-bit checksum, with a right rotation before each addition;
  83 overflow is discarded.
  84 .Pp
  85 Algorithm 2 is the algorithm used by historic
  86 .At V
  87 systems as the
  88 default
  89 .Xr sum 1
  90 algorithm.
  91 This is a 32-bit checksum, and is defined as follows:
  92 .Bd -unfilled -offset indent
  93 s = sum of all bytes;
  94 r = s % 2^16 + (s % 2^32) / 2^16;
  95 cksum = (r % 2^16) + r / 2^16;
  96 .Ed
  97 .Pp
  98 Algorithm 3 is what is commonly called the
  99 .Ql 32bit CRC
 100 algorithm.
 101 This is a 32-bit checksum.
 102 .Pp
 103 Both algorithm 1 and 2 write to the standard output the same fields as
 104 the default algorithm except that the size of the file in bytes is
 105 replaced with the size of the file in blocks.
 106 For historic reasons, the block size is 1024 for algorithm 1 and 512
 107 for algorithm 2.
 108 Partial blocks are rounded up.
 109 .El
 110 .Pp
 111 The default
 112 .Tn CRC
 113 used is based on the polynomial used for
 114 .Tn CRC
 115 error checking
 116 in the networking standard
 117 .St -iso8802-3 .
 118 The
 119 .Tn CRC
 120 checksum encoding is defined by the generating polynomial:
 121 .Bd -unfilled -offset indent
 122 G(x) = x^32 + x^26 + x^23 + x^22 + x^16 + x^12 +
 123      x^11 + x^10 + x^8 + x^7 + x^5 + x^4 + x^2 + x + 1
 124 .Ed
 125 .Pp
 126 Mathematically, the
 127 .Tn CRC
 128 value corresponding to a given file is defined by
 129 the following procedure:
 130 .Bd -ragged -offset indent
 131 The
 132 .Ar n
 133 bits to be evaluated are considered to be the coefficients of a mod 2
 134 polynomial M(x) of degree
 135 .Ar n Ns \-1 .
 136 These
 137 .Ar n
 138 bits are the bits from the file, with the most significant bit being the most
 139 significant bit of the first octet of the file and the last bit being the least
 140 significant bit of the last octet, padded with zero bits (if necessary) to
 141 achieve an integral number of octets, followed by one or more octets
 142 representing the length of the file as a binary value, least significant octet
 143 first.
 144 The smallest number of octets capable of representing this integer are used.
 145 .Pp
 146 M(x) is multiplied by x^32 (i.e., shifted left 32 bits) and divided by
 147 G(x) using mod 2 division, producing a remainder R(x) of degree <= 31.
 148 .Pp
 149 The coefficients of R(x) are considered to be a 32-bit sequence.
 150 .Pp
 151 The bit sequence is complemented and the result is the CRC.
 152 .Ed
 153 .Sh EXIT STATUS
 154 .Ex -std cksum sum
 155 .Sh SEE ALSO
 156 .Xr md5 1
 157 .Pp
 158 The default calculation is identical to that given in pseudo-code
 159 in the following
 160 .Tn ACM
 161 article.
 162 .Rs
 163 .%T "Computation of Cyclic Redundancy Checks Via Table Lookup"
 164 .%A Dilip V. Sarwate
 165 .%J "Communications of the" Tn ACM
 166 .%D "August 1988"
 167 .Re
 168 .Sh STANDARDS
 169 The
 170 .Nm
 171 utility is expected to conform to
 172 .St -p1003.2-92 .
 173 .Sh HISTORY
 174 The
 175 .Nm
 176 utility appeared in
 177 .Bx 4.4 .