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: src/usr.bin/cksum/cksum.1,v 1.19 2005/01/17 07:44:13 ru Exp $
  33 .\" $DragonFly: src/usr.bin/cksum/cksum.1,v 1.4 2008/05/02 02:05:07 swildner Exp $
  34 .\"
  35 .Dd April 28, 1995
  36 .Dt CKSUM 1
  37 .Os
  38 .Sh NAME
  39 .Nm cksum ,
  40 .Nm sum
  41 .Nd display file checksums and block counts
  42 .Sh SYNOPSIS
  43 .Nm
  44 .Op Fl o Ar 1 | 2 | 3
  45 .Op Ar
  46 .Nm sum
  47 .Op Ar
  48 .Sh DESCRIPTION
  49 The
  50 .Nm
  51 utility writes to the standard output three whitespace separated
  52 fields for each input file.
  53 These fields are a checksum
  54 .Tn CRC ,
  55 the total number of octets in the file and the file name.
  56 If no file name is specified, the standard input is used and no file name
  57 is written.
  58 .Pp
  59 The
  60 .Nm sum
  61 utility is identical to the
  62 .Nm
  63 utility, except that it defaults to using historic algorithm 1, as
  64 described below.
  65 It is provided for compatibility only.
  66 .Pp
  67 The options are as follows:
  68 .Bl -tag -width indent
  69 .It Fl o
  70 Use historic algorithms instead of the (superior) default one.
  71 .Pp
  72 Algorithm 1 is the algorithm used by historic
  73 .Bx
  74 systems as the
  75 .Xr sum 1
  76 algorithm and by historic
  77 .At V
  78 systems as the
  79 .Xr sum 1
  80 algorithm when using the
  81 .Fl r
  82 option.
  83 This is a 16-bit checksum, with a right rotation before each addition;
  84 overflow is discarded.
  85 .Pp
  86 Algorithm 2 is the algorithm used by historic
  87 .At V
  88 systems as the
  89 default
  90 .Xr sum 1
  91 algorithm.
  92 This is a 32-bit checksum, and is defined as follows:
  93 .Bd -unfilled -offset indent
  94 s = sum of all bytes;
  95 r = s % 2^16 + (s % 2^32) / 2^16;
  96 cksum = (r % 2^16) + r / 2^16;
  97 .Ed
  98 .Pp
  99 Algorithm 3 is what is commonly called the
 100 .Ql 32bit CRC
 101 algorithm.
 102 This is a 32-bit checksum.
 103 .Pp
 104 Both algorithm 1 and 2 write to the standard output the same fields as
 105 the default algorithm except that the size of the file in bytes is
 106 replaced with the size of the file in blocks.
 107 For historic reasons, the block size is 1024 for algorithm 1 and 512
 108 for algorithm 2.
 109 Partial blocks are rounded up.
 110 .El
 111 .Pp
 112 The default
 113 .Tn CRC
 114 used is based on the polynomial used for
 115 .Tn CRC
 116 error checking
 117 in the networking standard
 118 .St -iso8802-3 .
 119 The
 120 .Tn CRC
 121 checksum encoding is defined by the generating polynomial:
 122 .Bd -unfilled -offset indent
 123 G(x) = x^32 + x^26 + x^23 + x^22 + x^16 + x^12 +
 124      x^11 + x^10 + x^8 + x^7 + x^5 + x^4 + x^2 + x + 1
 125 .Ed
 126 .Pp
 127 Mathematically, the
 128 .Tn CRC
 129 value corresponding to a given file is defined by
 130 the following procedure:
 131 .Bd -ragged -offset indent
 132 The
 133 .Ar n
 134 bits to be evaluated are considered to be the coefficients of a mod 2
 135 polynomial M(x) of degree
 136 .Ar n Ns \-1 .
 137 These
 138 .Ar n
 139 bits are the bits from the file, with the most significant bit being the most
 140 significant bit of the first octet of the file and the last bit being the least
 141 significant bit of the last octet, padded with zero bits (if necessary) to
 142 achieve an integral number of octets, followed by one or more octets
 143 representing the length of the file as a binary value, least significant octet
 144 first.
 145 The smallest number of octets capable of representing this integer are used.
 146 .Pp
 147 M(x) is multiplied by x^32 (i.e., shifted left 32 bits) and divided by
 148 G(x) using mod 2 division, producing a remainder R(x) of degree \(<= 31.
 149 .Pp
 150 The coefficients of R(x) are considered to be a 32-bit sequence.
 151 .Pp
 152 The bit sequence is complemented and the result is the CRC.
 153 .Ed
 154 .Sh EXIT STATUS
 155 .Ex -std cksum sum
 156 .Sh SEE ALSO
 157 .Xr md5 1
 158 .Pp
 159 The default calculation is identical to that given in pseudo-code
 160 in the following
 161 .Tn ACM
 162 article.
 163 .Rs
 164 .%T "Computation of Cyclic Redundancy Checks Via Table Lookup"
 165 .%A Dilip V. Sarwate
 166 .%J "Communications of the" Tn ACM
 167 .%D "August 1988"
 168 .Re
 169 .Sh STANDARDS
 170 The
 171 .Nm
 172 utility is expected to conform to
 173 .St -p1003.2-92 .
 174 .Sh HISTORY
 175 The
 176 .Nm
 177 utility appeared in
 178 .Bx 4.4 .