path: root/usr/src/man/man1/sum.1

.\"
.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for
.\" permission to reproduce portions of its copyrighted documentation.
.\" Original documentation from The Open Group can be obtained online at
.\" http://www.opengroup.org/bookstore/.
.\"
.\" The Institute of Electrical and Electronics Engineers and The Open
.\" Group, have given us permission to reprint portions of their
.\" documentation.
.\"
.\" In the following statement, the phrase ``this text'' refers to portions
.\" of the system documentation.
.\"
.\" Portions of this text are reprinted and reproduced in electronic form
.\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition,
.\" Standard for Information Technology -- Portable Operating System
.\" Interface (POSIX), The Open Group Base Specifications Issue 6,
.\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics
.\" Engineers, Inc and The Open Group.  In the event of any discrepancy
.\" between these versions 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.
.\"
.\" This notice shall appear on any product containing this material.
.\"
.\" The contents of this file are subject to the terms of the
.\" Common Development and Distribution License (the "License").
.\" You may not use this file except in compliance with the License.
.\"
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
.\" or http://www.opensolaris.org/os/licensing.
.\" See the License for the specific language governing permissions
.\" and limitations under the License.
.\"
.\" When distributing Covered Code, include this CDDL HEADER in each
.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
.\" If applicable, add the following below this CDDL HEADER, with the
.\" fields enclosed by brackets "[]" replaced with your own identifying
.\" information: Portions Copyright [yyyy] [name of copyright owner]
.\"
.\"
.\" Copyright 1989 AT&T
.\" Copyright (c) 1992, X/Open Company Limited  All Rights Reserved
.\" Portions Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved.
.\"
.TH SUM 1 "May 23, 2021"
.SH NAME
sum \- print checksum and block count for a file
.SH SYNOPSIS
.nf
\fB/usr/bin/sum\fR [-abBchHlLpPrRstTw] [-x method] [\fIfile\fR...]
.fi

.SS "ksh93"
.nf
sum [-abBchHlLpPrRstTw] [-x method] [\fIfile\fR...]
.fi

.SH DESCRIPTION
The \fBsum\fR utility and ksh93 built-in command list the checksum, and for
most methods the block count, for each file argument. The standard input is
read if there are no file arguments.
.sp
.LP
The \fBgetconf\fR(1) \fBUNIVERSE\fR determines the default sum method: att for
the att universe, bsd otherwise. The default for the other commands is the
command name itself. The att method is a true sum, all others are order
dependent.
.sp
.LP
Method names consist of a leading identifier and 0 or more options separated by
-.
.sp
.LP
\fBgetconf\fR \fBPATH_RESOLVE\fR determines how symbolic links are handled.
This can be explicitly overridden by the \fB--logical\fR, \fB--metaphysical\fR,
and \fB--physical\fR options below. \fBPATH_RESOLVE\fR can be one of:
.sp
.ne 2
.na
\fB\fB--logical\fR\fR
.ad
.RS 18n
Follow all symbolic links.
.RE

.sp
.ne 2
.na
\fB\fB--metaphysical\fR\fR
.ad
.RS 18n
Follow command argument symbolic links, otherwise do not follow.
.RE

.sp
.ne 2
.na
\fB\fB--physical\fR\fR
.ad
.RS 18n
Do not follow symbolic links.
.RE

.SH OPTIONS
The following options are supported for \fB/usr/bin/sum\fR:
.sp
.ne 2
.na
\fB\fB-a\fR\fR
.ad
.br
.na
\fB\fB--all\fR\fR
.ad
.sp .6
.RS 4n
List the checksum for all files. Use with \fB--total\fR to list both individual
and total checksums and block counts.
.RE

.sp
.ne 2
.na
\fB\fB-b\fR\fR
.ad
.br
.na
\fB\fB--binary\fR\fR
.ad
.sp .6
.RS 4n
Read files in binary mode. This is the default.
.RE

.sp
.ne 2
.na
\fB\fB-B\fR\fR
.ad
.br
.na
\fB\fB--scale=scale\fR\fR
.ad
.sp .6
.RS 4n
Block count scale (bytes per block) override for methods that include size in
the output. The default is method-specific.
.RE

.sp
.ne 2
.na
\fB\fB-c\fR\fR
.ad
.br
.na
\fB\fB--check\fR\fR
.ad
.sp .6
.RS 4n
Each file is interpreted as the output from a previous sum. If \fB--header\fR
or \fB--permissions\fR was specified in the previous sum then the checksum
method is automatically determined, otherwise \fB--method\fR must be specified.
The listed checksum is compared with the current value and a warning is issued
for each file that does not match. If file was generated by
\fB--permissions\fR, then the file mode, user and group are also checked. Empty
lines, lines starting with #<space>, or the line # are ignored. Lines
containing no blanks are interpreted as [no]name[=\fIvalue\fR] options:
.sp
.ne 2
.na
\fB\fBmethod=name\fR\fR
.ad
.sp .6
.RS 4n
Checksum method to apply to subsequent lines.
.RE

.sp
.ne 2
.na
\fB\fBpermissions\fR\fR
.ad
.sp .6
.RS 4n
Subsequent lines were generated with \fB--permissions\fR.
.RE

.RE

.sp
.ne 2
.na
\fB\fB-h\fR\fR
.ad
.br
.na
\fB\fB--header\fR\fR
.ad
.sp .6
.RS 4n
Print the checksum method as the first output line. Used with \fB--check\fR and
\fB--permissions\fR.
.RE

.sp
.ne 2
.na
\fB\fB-l\fR\fR
.ad
.br
.na
\fB\fB--list\fR\fR
.ad
.sp .6
.RS 4n
Each file is interpreted as a list of files, one per line, that is checksummed.
.RE

.sp
.ne 2
.na
\fB\fB-p\fR\fR
.ad
.br
.na
\fB\fB--permissions\fR\fR
.ad
.sp .6
.RS 4n
If \fB--check\fR is not specified then list the file mode, user and group
between the checksum and path. User and group matching the caller are output as
-. If \fB--check\fR is specified then the mode, user and group for each path in
file are updated if necessary to match those in file. A warning is printed on
the standard error for each changed file.
.RE

.sp
.ne 2
.na
\fB\fB-R\fR\fR
.ad
.br
.na
\fB\fB--recursive\fR\fR
.ad
.sp .6
.RS 4n
Recursively checksum the contents of directories.
.RE

.sp
.ne 2
.na
\fB\fB-t\fR\fR
.ad
.br
.na
\fB\fB--total\fR\fR
.ad
.sp .6
.RS 4n
List only the total checksum and block count of all files. \fB--all\fR
\fB--total\fR lists each checksum and the total. The total checksum and block
count may be different from the checksum and block count of the catenation of
all files due to partial blocks that may occur when the files are treated
separately.
.RE

.sp
.ne 2
.na
\fB\fB-T\fR\fR
.ad
.br
.na
\fB\fB--text\fR\fR
.ad
.sp .6
.RS 4n
Read files in text mode (for example, treat \er\en as \en).
.RE

.sp
.ne 2
.na
\fB\fB-w\fR\fR
.ad
.br
.na
\fB\fB--warn\fR\fR
.ad
.sp .6
.RS 4n
Warn about invalid \fB--check\fR lines. On by default; \fB-w\fR means
\fB--nowarn\fR.
.RE

.sp
.ne 2
.na
\fB\fB-x\fR\fR
.ad
.br
.na
\fB\fB--method|algorithm=method\fR\fR
.ad
.sp .6
.RS 4n
Specifies the checksum method to apply. Parenthesized method options are
readonly implementation details.
.sp
.ne 2
.na
\fB\fBatt\fR|\fBsys5\fR|\fBs5\fR|\fBdefault\fR\fR
.ad
.sp .6
.RS 4n
The system 5 release 4 checksum. This is the default for sum when \fBgetconf\fR
\fBUNIVERSE\fR is \fBatt\fR. This is the only true sum; all of the other
methods are order dependent.
.RE

.sp
.ne 2
.na
\fB\fBast4\fR|\fB32x4\fR|\fBtw\fR\fR
.ad
.sp .6
.RS 4n
The \fBast\fR 128 bit \fBPRNG\fR hash generated by catenating 4 separate 32 bit
\fBPNRG\fR hashes. The block count is not printed.
.RE

.sp
.ne 2
.na
\fB\fBbsd\fR|\fBucb\fR\fR
.ad
.sp .6
.RS 4n
The BSD checksum.
.RE

.sp
.ne 2
.na
\fB\fBcrc\fR\fR
.ad
.sp .6
.RS 4n
32 bit CRC (cyclic redundancy check).
.sp
.ne 2
.na
\fB\fBpolynomial\fR=\fImask\fR\fR
.ad
.sp .6
.RS 4n
The 32 bit \fBcrc\fR polynomial bitmask with implicit bit 32. The default value
is 0xedb88320.
.RE

.sp
.ne 2
.na
\fB\fBdone\fR[=\fInumber\fR]\fR
.ad
.sp .6
.RS 4n
XOR the final \fBcrc\fR value with number. 0xffffffff is used if number is
omitted. The option value may be omitted. The default value is 0.
.RE

.sp
.ne 2
.na
\fB\fBinit\fR[=\fInumber\fR]\fR
.ad
.sp .6
.RS 4n
The initial \fBcrc\fR value. 0xffffffff is used if number is omitted. The
option value may be omitted. The default value is 0.
.RE

.sp
.ne 2
.na
\fB\fBrotate\fR\fR
.ad
.sp .6
.RS 4n
XOR each input character with the high order \fBcrc\fR byte (instead of the low
order).
.RE

.sp
.ne 2
.na
\fB\fBsize\fR[=\fInumber\fR]\fR
.ad
.sp .6
.RS 4n
Include the total number of bytes in the crc. number, if specified, is first
XOR'd into the size. The option value may be omitted. The default value is 0.
.RE

.RE

.sp
.ne 2
.na
\fB\fBprng\fR\fR
.ad
.sp .6
.RS 4n
32 bit \fBPRNG\fR (pseudo random number generator) hash.
.sp
.ne 2
.na
\fB\fBmpy\fR=\fInumber\fR\fR
.ad
.RS 17n
The 32 bit \fBPRNG\fR multiplier. The default value is 0x01000193.
.RE

.sp
.ne 2
.na
\fB\fBadd\fR=\fInumber\fR\fR
.ad
.RS 17n
The 32 bit \fBPRNG\fR addend. The default value is 0.
.RE

.sp
.ne 2
.na
\fB\fBinit\fR[=\fInumber\fR]\fR
.ad
.RS 17n
The \fBPRNG\fR initial value. 0xffffffff is used if number is omitted. The
option value may be omitted. The default value is 0x811c9dc5.
.RE

.RE

.sp
.ne 2
.na
\fB\fBmd4\fR|\fBMD4\fR\fR
.ad
.sp .6
.RS 4n
\fBRFC1320\fR \fBMD4\fR message digest. Cryptographically weak. The block count
is not printed.  (version) \fBmd4\fR (\fBsolaris\fR \fB-lmd\fR) 2005-07-26
.RE

.sp
.ne 2
.na
\fB\fBmd5\fR|\fBMD5\fR\fR
.ad
.sp .6
.RS 4n
\fBRFC1321\fR \fBMD5\fR message digest. Cryptographically weak. The block count
is not printed. (version) \fBmd5\fR (\fBsolaris\fR \fB-lmd\fR) 2005-07-26
.RE

.sp
.ne 2
.na
\fB\fBsha1\fR|\fBSHA1\fR|\fBsha-1\fR|\fBSHA-1\fR\fR
.ad
.sp .6
.RS 4n
\fBRFC3174\fR / \fBFIPS 180-1\fR \fBSHA-1\fR secure hash algorithm 1.
Cryptographically weak. The block count is not printed. (version) \fBsha1\fR
(\fBsolaris\fR \fB-lmd\fR) 2005-07-26
.RE

.sp
.ne 2
.na
\fB\fBsha256\fR|\fBsha-256\fR|\fBSHA256\fR|\fBSHA-256\fR\fR
.ad
.sp .6
.RS 4n
\fBFIPS 180-2\fR \fBSHA256\fR secure hash algorithm. The block count is not
printed. (version) \fBsha256\fR (\fBsolaris\fR \fB-lmd\fR) 2005-07-26
.RE

.sp
.ne 2
.na
\fB\fBsha384\fR|\fBsha-384\fR|\fBSHA384\fR|\fBSHA-384\fR\fR
.ad
.sp .6
.RS 4n
\fBFIPS 180-2\fR \fBSHA384\fR secure hash algorithm. The block count is not
printed. (version) \fBsha384\fR (\fBsolaris\fR \fB-lmd\fR) 2005-07-26
.RE

.sp
.ne 2
.na
\fB\fBsha512\fR|\fBsha-512\fR|\fBSHA512\fR|\fBSHA-512\fR\fR
.ad
.sp .6
.RS 4n
\fBFIPS 180-2\fR \fBSHA512\fR secure hash algorithm. The block count is not
printed. (version) \fBsha512\fR (\fBsolaris\fR \fB-lmd\fR) 2005-07-26
.RE

.sp
.ne 2
.na
\fB\fBposix\fR|\fBcksum\fR|\fBstd\fR|\fBstandard\fR\fR
.ad
.sp .6
.RS 4n
The \fBposix 1003.2-1992\fR 32 bit \fBcrc\fR checksum. This is the default
\fBcksum\fR(1) method. Shorthand for \fBcrc-0x04c11db7-rotate-done-size\fR.
.RE

.sp
.ne 2
.na
\fB\fBzip\fR\fR
.ad
.sp .6
.RS 4n
The \fBzip\fR(1) \fBcrc\fR. Shorthand for \fBcrc-0xedb88320-init-done\fR.
.RE

.sp
.ne 2
.na
\fB\fBfddi\fR\fR
.ad
.sp .6
.RS 4n
The \fBFDDI\fR \fBcrc\fR. Shorthand for
\fBcrc-0xedb88320-size\fR=\fB0xcc55cc55\fR.
.RE

.sp
.ne 2
.na
\fB\fBfnv\fR|\fBfnv1\fR\fR
.ad
.sp .6
.RS 4n
The \fBFowler-Noll-Vo\fR 32 bit \fBPRNG\fR hash with non-zero initializer
(\fBFNV-1\fR). Shorthand for \fBprng-0x01000193-init\fR=\fB0x811c9dc5\fR.
.RE

.sp
.ne 2
.na
\fB\fBast\fR|\fBstrsum\fR\fR
.ad
.sp .6
.RS 4n
The \fBast\fR \fBstrsum\fR \fBPRNG\fR hash. Shorthand for
\fBprng-0x63c63cd9-add\fR=\fB0x9c39c33d\fR.
.RE

.RE

.sp
.ne 2
.na
\fB\fB-L\fR\fR
.ad
.br
.na
\fB\fB--logical\fR|\fBfollow\fR\fR
.ad
.sp .6
.RS 4n
Follow symbolic links when traversing directories. The default is determined by
\fBgetconf\fR \fBPATH_RESOLVE\fR.
.RE

.sp
.ne 2
.na
\fB\fB-H\fR\fR
.ad
.br
.na
\fB\fB--metaphysical\fR\fR
.ad
.sp .6
.RS 4n
Follow command argument symbolic links, otherwise do not follow symbolic links
when traversing directories. The default is determined by \fBgetconf\fR
\fBPATH_RESOLVE\fR.
.RE

.sp
.ne 2
.na
\fB\fB-P\fR\fR
.ad
.br
.na
\fB\fB--physical\fR\fR
.ad
.sp .6
.RS 4n
Do not follow symbolic links when traversing directories. The default is
determined by \fBgetconf\fR \fBPATH_RESOLVE\fR.
.RE

.sp
.ne 2
.na
\fB\fB-r\fR\fR
.ad
.br
.na
\fB\fB--bsd\fR\fR
.ad
.sp .6
.RS 4n
Equivalent to \fB--method=bsd\fR \fB--scale=512\fR for compatibility with other
sum implementations.
.RE

.sp
.ne 2
.na
\fB\fB-s\fR\fR
.ad
.br
.na
\fB\fB--sysv\fR\fR
.ad
.sp .6
.RS 4n
Equivalent to \fB--method=sys5\fR for compatibility with other sum
implementations.
.RE

.sp
.ne 2
.na
\fB\fB-S\fR\fR
.ad
.br
.na
\fB\fB--silent\fR|\fBstatus\fR\fR
.ad
.sp .6
.RS 4n
No output for \fB--check\fR;  0 exit status means all sums matched, non-0 means
at least one sum failed to match. Ignored for \fB--permissions\fR.
.RE

.SH OPERANDS
The following operands are supported:
.sp
.ne 2
.na
\fB\fIfile\fR\fR
.ad
.RS 8n
A path name of a file.  If no files are named, the standard input is used.
.RE

.SH USAGE
See \fBlargefile\fR(7) for the description of the behavior of \fBsum\fR when
encountering files greater than or equal to 2 Gbyte ( 2^31 bytes).
.SH ENVIRONMENT VARIABLES
See \fBenviron\fR(7) for descriptions of the following environment variables
that affect the execution of  \fBsum\fR: \fBLC_CTYPE\fR, \fBLC_MESSAGES\fR, and
\fBNLSPATH\fR.
.SH EXIT STATUS
The following exit values are returned.
.sp
.ne 2
.na
\fB\fB0\fR\fR
.ad
.RS 6n
Successful completion.
.RE

.sp
.ne 2
.na
\fB\fB>0\fR\fR
.ad
.RS 6n
An error occurred.
.RE

.SH ATTRIBUTES
See \fBattributes\fR(7) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
CSI	Enabled
.TE

.SH SEE ALSO
.BR cksum (1),
.BR digest (1),
.BR getconf (1),
.BR ksh93 (1),
.BR wc (1),
.BR zip (1),
.BR sum (1B),
.BR libmd (3LIB),
.BR attributes (7),
.BR environ (7),
.BR largefile (7)
.SH DIAGNOSTICS
\fBRead error\fR is indistinguishable from end of file on most devices. Check
the block count.
.SH NOTES
Portable applications should use \fBcksum\fR(1). The default algorithm for this
command is defined in the POSIX standard and is identical across platforms.
.sp
.LP
\fBsum\fR and \fB/usr/ucb/sum\fR (see \fBsum\fR(1B)) return different checksums.