path: root/sha3-256sum.1

.TH SHA3-256SUM 1 anysum
.SH NAME
sha3-256sum - compute or verify against multiple SHA3-256 hashes

.SH SYNOPSIS
.B sha3-256sum
.RB [ -c
.RB [ -w ]]
.RB [ -W
.IR options ]\ ...
.RB [ -z ]
.RI [ file ]\ ...

.SH DESCRIPTION
The
.B sha3-256sum
utility calculates and prints or checks SHA3-256
checksums.
.PP
The
.B sha3-256sum
utility can also check a file against multiple SHA3-256
checksums, and check that the file matches at least one
of the listed checksums.

.SH OPTIONS
The sha3-256sum utility conforms to the Base Definitions
volume of POSIX.1-2017,
.IR "Section 12.2" ,
.IR "Utility Syntax Guidelines" .
.PP
The following options are supported:
.TP
.B -b
Equivalent to
.BR "-W output=binary" .
.TP
.B -c
Verify the the files listed in file against the
checksums listed on the same lines. The file
shall be formatted as the output of the utility
when this option is not used. See the
.B STDOUT
section for more information. If a file is listed
multiple times, it need only match one of the
checksums listed for the file.

The length of the listed checksums need not match
the length output by this utility; before the
checksums are compared, they are truncated to the
shorter of the two checksums.
.TP
.B -l
Equivalent to
.BR "-W output=lowercase" .
.TP
.B -u
Equivalent to
.BR "-W output=uppercase" .
.TP
.B -v
Print Keccak parameters to standard error.
.TP
.BR -W \ \fIoptions\fP
Comma-sepearated list of implementation-specific
options. The following options are supported:
.RS
.TP
.BI output= format
.I format
shall be
.RB \(dq lowercase \(dq
if the checksums shall be printed in lowercase
hexadecimal format (default),
.RB \(dq uppercase \(dq
for uppercase hexadecimal format, or
.RB \(dq binary \(dq
for binary format without anything but the
checksum printed to standard output. This
option is ignored if the
.B -c
option is used.
.TP
.BI input= format
.I format
shall be
.RB \(dq binary \(dq
if the files are be read in binary mode,
.RB \(dq text \(dq
if the files shall be read in text mode, or
.RB \(dq hexadecimal \(dq
they shall be decoded from hexadecimal to
binary. If the
.B -c
option is used, the mode specification
associated with a file is overrides this
behaviour for that file if the line
specifies hexadecimal mode.
.TP
.B recursive
If a
.I file
operand is a directory, the checksum is computed for
all files recursively. This option is ignored if the
.B -c
option is used.
.TP
.B no-recursive
The utility shall traverse directories.
(This is the default behaviour).
.TP
.B xdev
Implies
.B -W recursive
but also allows the recursion across mountpoints.
.TP
.B no-xdev
Disable recursion across mountpoints.
(This is the default behaviour).
Note that this does not disable
recursion by itself.
.TP
.B xlink
Implies
.B -W recursive
but also allows the recursion across symbolic links.
.TP
.B no-xlink
Disable recursion across symbolic links.
(This is the default behaviour).
Note that this does not disable
recursion by itself.
.RE
.TP
.B -w
Warn about, but skip, lines that are not properly
formatted.
.TP
.B -x
Equivalent to
.BR "-W input=hexadeximal" .
.TP
.B -z
Use NUL byte as line ending instead of LF.
.PP
There is no difference between binary mode and text mode.

.SH OPERANDS
The following operand is supported:
.TP
.I file
The file to read and compute the checksum for, or if the
.B -c
option is used, use as the listing of files and checksums
to verify the files against. If dash
.RB (' - ')
is used or if no file operand is specified, standard input
will be used.

.SH STDOUT
If the
.B -c
option is not used, the utility shall print the following
line for each calculated checksum, however there are options
that modify the format; see the
.B OPTIONS
section for more information:
.PP
.RS
.B \(dq%s %c%s\en\(dq,
.RI < hash >\fB,\fP
.RI < mode >\fB,\fP
.RI < file >
.RE
.PP
where
.I mode
is SP (' ') for text mode, an asterisk
.RB (' * ')
for binary mode, or a pound sign
.RB (' # ')
for hexadecimal mode; however if there is no difference
between binary mode and text mode and either is selected,
SP (' ') (text mode) is used.
.PP
If the
.B -c
option the output shall be on the format:
.PP
.RS
.B \(dq%s: %s\en\(dq,
.RI < file >\fB,\fP
.RI < validity >
.RE
.PP
where
.I validity
is an implementation specified string
that describes whether the checksum was valid (possibly
with remarks), the file did not exist, the file could
not be read (possibly with error information), or if
the checksum was invalid or could not be compared
(possibly with remarks). The
.B -z
option does not modify the line ending.

.SH EXIT STATUS
The following exit values are returned:
.TP
0
Successful completion.
.TP
1
Checksums did not match or a file did not exist.
.TP
2
An error occurred.

.SH NOTES
Other implementations do not necessarily recognise the
hexadecimal mode specifier
.RB (' # ')
in checksum list files.
.PP
The
.B -c
option accepting truncated checksums is an
implementation-specific behaviour.

.SH SEE ALSO
.BR anysum (1)