1CKSUM(1P) POSIX Programmer's Manual CKSUM(1P)
2
3
4
6 This manual page is part of the POSIX Programmer's Manual. The Linux
7 implementation of this interface may differ (consult the corresponding
8 Linux manual page for details of Linux behavior), or the interface may
9 not be implemented on Linux.
10
12 cksum — write file checksums and sizes
13
15 cksum [file...]
16
18 The cksum utility shall calculate and write to standard output a cyclic
19 redundancy check (CRC) for each input file, and also write to standard
20 output the number of octets in each file. The CRC used is based on the
21 polynomial used for CRC error checking in the ISO/IEC 8802‐3:1996 stan‐
22 dard (Ethernet).
23
24 The encoding for the CRC checksum is defined by the generating polyno‐
25 mial:
26
27
28 G(x)=x32+x26+x23+x22+x16+x12+x11+x10+x8+x7+x5+x4+x2+x+1
29
30 Mathematically, the CRC value corresponding to a given file shall be
31 defined by the following procedure:
32
33 1. The n bits to be evaluated are considered to be the coefficients of
34 a mod 2 polynomial M(x) of degree n-1. These n bits are the bits
35 from the file, with the most significant bit being the most signif‐
36 icant bit of the first octet of the file and the last bit being the
37 least significant bit of the last octet, padded with zero bits (if
38 necessary) to achieve an integral number of octets, followed by one
39 or more octets representing the length of the file as a binary
40 value, least significant octet first. The smallest number of octets
41 capable of representing this integer shall be used.
42
43 2. M(x) is multiplied by x32 (that is, shifted left 32 bits) and
44 divided by G(x) using mod 2 division, producing a remainder R(x) of
45 degree ≤ 31.
46
47 3. The coefficients of R(x) are considered to be a 32-bit sequence.
48
49 4. The bit sequence is complemented and the result is the CRC.
50
52 None.
53
55 The following operand shall be supported:
56
57 file A pathname of a file to be checked. If no file operands are
58 specified, the standard input shall be used.
59
61 The standard input shall be used if no file operands are specified, and
62 shall be used if a file operand is '-' and the implementation treats
63 the '-' as meaning standard input. Otherwise, the standard input shall
64 not be used. See the INPUT FILES section.
65
67 The input files can be any file type.
68
70 The following environment variables shall affect the execution of
71 cksum:
72
73 LANG Provide a default value for the internationalization vari‐
74 ables that are unset or null. (See the Base Definitions vol‐
75 ume of POSIX.1‐2017, Section 8.2, Internationalization Vari‐
76 ables for the precedence of internationalization variables
77 used to determine the values of locale categories.)
78
79 LC_ALL If set to a non-empty string value, override the values of
80 all the other internationalization variables.
81
82 LC_CTYPE Determine the locale for the interpretation of sequences of
83 bytes of text data as characters (for example, single-byte as
84 opposed to multi-byte characters in arguments).
85
86 LC_MESSAGES
87 Determine the locale that should be used to affect the format
88 and contents of diagnostic messages written to standard
89 error.
90
91 NLSPATH Determine the location of message catalogs for the processing
92 of LC_MESSAGES.
93
95 Default.
96
98 For each file processed successfully, the cksum utility shall write in
99 the following format:
100
101
102 "%u %d %s\n", <checksum>, <# of octets>, <pathname>
103
104 If no file operand was specified, the pathname and its leading <space>
105 shall be omitted.
106
108 The standard error shall be used only for diagnostic messages.
109
111 None.
112
114 None.
115
117 The following exit values shall be returned:
118
119 0 All files were processed successfully.
120
121 >0 An error occurred.
122
124 Default.
125
126 The following sections are informative.
127
129 The cksum utility is typically used to quickly compare a suspect file
130 against a trusted version of the same, such as to ensure that files
131 transmitted over noisy media arrive intact. However, this comparison
132 cannot be considered cryptographically secure. The chances of a damaged
133 file producing the same CRC as the original are small; deliberate
134 deception is difficult, but probably not impossible.
135
136 Although input files to cksum can be any type, the results need not be
137 what would be expected on character special device files or on file
138 types not described by the System Interfaces volume of POSIX.1‐2017.
139 Since this volume of POSIX.1‐2017 does not specify the block size used
140 when doing input, checksums of character special files need not process
141 all of the data in those files.
142
143 The algorithm is expressed in terms of a bitstream divided into octets.
144 If a file is transmitted between two systems and undergoes any data
145 transformation (such as changing little-endian byte ordering to big-
146 endian), identical CRC values cannot be expected. Implementations per‐
147 forming such transformations may extend cksum to handle such situa‐
148 tions.
149
151 None.
152
154 The following C-language program can be used as a model to describe the
155 algorithm. It assumes that a char is one octet. It also assumes that
156 the entire file is available for one pass through the function. This
157 was done for simplicity in demonstrating the algorithm, rather than as
158 an implementation model.
159
160
161 static unsigned long crctab[] = {
162 0x00000000,
163 0x04c11db7, 0x09823b6e, 0x0d4326d9, 0x130476dc, 0x17c56b6b,
164 0x1a864db2, 0x1e475005, 0x2608edb8, 0x22c9f00f, 0x2f8ad6d6,
165 0x2b4bcb61, 0x350c9b64, 0x31cd86d3, 0x3c8ea00a, 0x384fbdbd,
166 0x4c11db70, 0x48d0c6c7, 0x4593e01e, 0x4152fda9, 0x5f15adac,
167 0x5bd4b01b, 0x569796c2, 0x52568b75, 0x6a1936c8, 0x6ed82b7f,
168 0x639b0da6, 0x675a1011, 0x791d4014, 0x7ddc5da3, 0x709f7b7a,
169 0x745e66cd, 0x9823b6e0, 0x9ce2ab57, 0x91a18d8e, 0x95609039,
170 0x8b27c03c, 0x8fe6dd8b, 0x82a5fb52, 0x8664e6e5, 0xbe2b5b58,
171 0xbaea46ef, 0xb7a96036, 0xb3687d81, 0xad2f2d84, 0xa9ee3033,
172 0xa4ad16ea, 0xa06c0b5d, 0xd4326d90, 0xd0f37027, 0xddb056fe,
173 0xd9714b49, 0xc7361b4c, 0xc3f706fb, 0xceb42022, 0xca753d95,
174 0xf23a8028, 0xf6fb9d9f, 0xfbb8bb46, 0xff79a6f1, 0xe13ef6f4,
175 0xe5ffeb43, 0xe8bccd9a, 0xec7dd02d, 0x34867077, 0x30476dc0,
176 0x3d044b19, 0x39c556ae, 0x278206ab, 0x23431b1c, 0x2e003dc5,
177 0x2ac12072, 0x128e9dcf, 0x164f8078, 0x1b0ca6a1, 0x1fcdbb16,
178 0x018aeb13, 0x054bf6a4, 0x0808d07d, 0x0cc9cdca, 0x7897ab07,
179 0x7c56b6b0, 0x71159069, 0x75d48dde, 0x6b93dddb, 0x6f52c06c,
180 0x6211e6b5, 0x66d0fb02, 0x5e9f46bf, 0x5a5e5b08, 0x571d7dd1,
181 0x53dc6066, 0x4d9b3063, 0x495a2dd4, 0x44190b0d, 0x40d816ba,
182 0xaca5c697, 0xa864db20, 0xa527fdf9, 0xa1e6e04e, 0xbfa1b04b,
183 0xbb60adfc, 0xb6238b25, 0xb2e29692, 0x8aad2b2f, 0x8e6c3698,
184 0x832f1041, 0x87ee0df6, 0x99a95df3, 0x9d684044, 0x902b669d,
185 0x94ea7b2a, 0xe0b41de7, 0xe4750050, 0xe9362689, 0xedf73b3e,
186 0xf3b06b3b, 0xf771768c, 0xfa325055, 0xfef34de2, 0xc6bcf05f,
187 0xc27dede8, 0xcf3ecb31, 0xcbffd686, 0xd5b88683, 0xd1799b34,
188 0xdc3abded, 0xd8fba05a, 0x690ce0ee, 0x6dcdfd59, 0x608edb80,
189 0x644fc637, 0x7a089632, 0x7ec98b85, 0x738aad5c, 0x774bb0eb,
190 0x4f040d56, 0x4bc510e1, 0x46863638, 0x42472b8f, 0x5c007b8a,
191 0x58c1663d, 0x558240e4, 0x51435d53, 0x251d3b9e, 0x21dc2629,
192 0x2c9f00f0, 0x285e1d47, 0x36194d42, 0x32d850f5, 0x3f9b762c,
193 0x3b5a6b9b, 0x0315d626, 0x07d4cb91, 0x0a97ed48, 0x0e56f0ff,
194 0x1011a0fa, 0x14d0bd4d, 0x19939b94, 0x1d528623, 0xf12f560e,
195 0xf5ee4bb9, 0xf8ad6d60, 0xfc6c70d7, 0xe22b20d2, 0xe6ea3d65,
196 0xeba91bbc, 0xef68060b, 0xd727bbb6, 0xd3e6a601, 0xdea580d8,
197 0xda649d6f, 0xc423cd6a, 0xc0e2d0dd, 0xcda1f604, 0xc960ebb3,
198 0xbd3e8d7e, 0xb9ff90c9, 0xb4bcb610, 0xb07daba7, 0xae3afba2,
199 0xaafbe615, 0xa7b8c0cc, 0xa379dd7b, 0x9b3660c6, 0x9ff77d71,
200 0x92b45ba8, 0x9675461f, 0x8832161a, 0x8cf30bad, 0x81b02d74,
201 0x857130c3, 0x5d8a9099, 0x594b8d2e, 0x5408abf7, 0x50c9b640,
202 0x4e8ee645, 0x4a4ffbf2, 0x470cdd2b, 0x43cdc09c, 0x7b827d21,
203 0x7f436096, 0x7200464f, 0x76c15bf8, 0x68860bfd, 0x6c47164a,
204 0x61043093, 0x65c52d24, 0x119b4be9, 0x155a565e, 0x18197087,
205 0x1cd86d30, 0x029f3d35, 0x065e2082, 0x0b1d065b, 0x0fdc1bec,
206 0x3793a651, 0x3352bbe6, 0x3e119d3f, 0x3ad08088, 0x2497d08d,
207 0x2056cd3a, 0x2d15ebe3, 0x29d4f654, 0xc5a92679, 0xc1683bce,
208 0xcc2b1d17, 0xc8ea00a0, 0xd6ad50a5, 0xd26c4d12, 0xdf2f6bcb,
209 0xdbee767c, 0xe3a1cbc1, 0xe760d676, 0xea23f0af, 0xeee2ed18,
210 0xf0a5bd1d, 0xf464a0aa, 0xf9278673, 0xfde69bc4, 0x89b8fd09,
211 0x8d79e0be, 0x803ac667, 0x84fbdbd0, 0x9abc8bd5, 0x9e7d9662,
212 0x933eb0bb, 0x97ffad0c, 0xafb010b1, 0xab710d06, 0xa6322bdf,
213 0xa2f33668, 0xbcb4666d, 0xb8757bda, 0xb5365d03, 0xb1f740b4
214 };
215
216 unsigned long memcrc(const unsigned char *b, size_t n)
217 {
218 /* Input arguments:
219 * const unsigned char* b == byte sequence to checksum
220 * size_t n == length of sequence
221 */
222
223 register size_t i;
224 register unsigned c, s = 0;
225
226 for (i = n; i > 0; --i) {
227 c = *b++;
228 s = (s << 8) ^ crctab[(s >> 24) ^ c];
229 }
230
231 /* Extend with the length of the string. */
232 while (n != 0) {
233 c = n & 0377;
234 n >>= 8;
235 s = (s << 8) ^ crctab[(s >> 24) ^ c];
236 }
237
238 return ~s;
239 }
240
241 The historical practice of writing the number of ``blocks'' has been
242 changed to writing the number of octets, since the latter is not only
243 more useful, but also since historical implementations have not been
244 consistent in defining what a ``block'' meant.
245
246 The algorithm used was selected to increase the operational robustness
247 of cksum. Neither the System V nor BSD sum algorithm was selected.
248 Since each of these was different and each was the default behavior on
249 those systems, no realistic compromise was available if either were
250 selected—some set of historical applications would break. Therefore,
251 the name was changed to cksum. Although the historical sum commands
252 will probably continue to be provided for many years, programs designed
253 for portability across systems should use the new name.
254
255 The algorithm selected is based on that used by the ISO/IEC 8802‐3:1996
256 standard (Ethernet) for the frame check sequence field. The algorithm
257 used does not match the technical definition of a checksum; the term is
258 used for historical reasons. The length of the file is included in the
259 CRC calculation because this parallels inclusion of a length field by
260 Ethernet in its CRC, but also because it guards against inadvertent
261 collisions between files that begin with different series of zero
262 octets. The chance that two different files produce identical CRCs is
263 much greater when their lengths are not considered. Keeping the length
264 and the checksum of the file itself separate would yield a slightly
265 more robust algorithm, but historical usage has always been that a sin‐
266 gle number (the checksum as printed) represents the signature of the
267 file. It was decided that historical usage was the more important con‐
268 sideration.
269
270 Early proposals contained modifications to the Ethernet algorithm that
271 involved extracting table values whenever an intermediate result became
272 zero. This was demonstrated to be less robust than the current method
273 and mathematically difficult to describe or justify.
274
275 The calculation used is identical to that given in pseudo-code in the
276 referenced Sarwate article. The pseudo-code rendition is:
277
278
279 X <- 0; Y <- 0;
280 for i <- m -1 step -1 until 0 do
281 begin
282 T <- X(1) ^ A[i];
283 X(1) <- X(0); X(0) <- Y(1); Y(1) <- Y(0); Y(0) <- 0;
284 comment: f[T] and f'[T] denote the T-th words in the
285 table f and f' ;
286 X <- X ^ f[T]; Y <- Y ^ f'[T];
287 end
288
289 The pseudo-code is reproduced exactly as given; however, note that in
290 the case of cksum, A[i] represents a byte of the file, the words X and
291 Y are treated as a single 32-bit value, and the tables f and f' are a
292 single table containing 32-bit values.
293
294 The referenced Sarwate article also discusses generating the table.
295
297 None.
298
300 The Base Definitions volume of POSIX.1‐2017, Chapter 8, Environment
301 Variables
302
304 Portions of this text are reprinted and reproduced in electronic form
305 from IEEE Std 1003.1-2017, Standard for Information Technology -- Por‐
306 table Operating System Interface (POSIX), The Open Group Base Specifi‐
307 cations Issue 7, 2018 Edition, Copyright (C) 2018 by the Institute of
308 Electrical and Electronics Engineers, Inc and The Open Group. In the
309 event of any discrepancy between this version and the original IEEE and
310 The Open Group Standard, the original IEEE and The Open Group Standard
311 is the referee document. The original Standard can be obtained online
312 at http://www.opengroup.org/unix/online.html .
313
314 Any typographical or formatting errors that appear in this page are
315 most likely to have been introduced during the conversion of the source
316 files to man page format. To report such errors, see https://www.ker‐
317 nel.org/doc/man-pages/reporting_bugs.html .
318
319
320
321IEEE/The Open Group 2017 CKSUM(1P)