XCKS(1) | General Commands Manual

3rd March 2022

NAME

xcks - calculates or verifies XCKS and ZXCKS checksums’ files

SYNOPSIS

  1. xcks [options]
  2. xcks [options] <(Z)XCKS_file>
  3. xcks --verify <(Z)XCKS_file> [options]
  4. xcks --create <(Z)XCKS_file> [options] [file|directory]…
  5. xcks --list-profiles [–wordiness <arg>]
  6. xcks [--help|--version]

DESCRIPTION

xcks is a tool for creating or verifying checksums of files.

xcks reads and stores calculated checksums in XCKS and ZXCKS checksums’ files.

  1. Reads a (Z)XCKS checksums’ file from the standard input (stdin), and verifies files present in the read (Z)XCKS checksums’ file.
  2. Reads a (Z)XCKS checksums’ file from <(Z)XCKS_file> or from the standard input (stdin) if <(Z)XCKS_file> is -, and verifies files present in the read (Z)XCKS checksums’ file.
  3. Reads a (Z)XCKS checksums’ file from <(Z)XCKS_file> or from the standard input (stdin) if <(Z)XCKS_file> is -, and verifies files present in the read (Z)XCKS checksums’ file.
  4. Calcultes the checksums of the given files or directories and stores them in a (Z)XCKS checksums’ file or the standard output (stdout) if <(Z)XCKS_file> is -.
  5. Lists the known profiles (list of algorithms of checksums).
  6. Shows the help or the version of the program.

OPTIONS

boolean_arg are arguments for options that takes a boolean value. If these options are explicitly set on the command line without argument, they are implicity set to on.

Valids values for boolean_arg are on, true, yes and off, false, no.

The -- (dash dash) element may be used on the command line to signify to xcks to end the dectection of command options at this point.

General options

-h, --help
Shows help.
-V, --version
Shows version.
-w,–wordiness arg

Level of wordiness: mute, quiet, progress, values, chatterbox

-T, --threads arg
Number of threads to use to compute the checksums (0 = number of cores of the computer).
-X, --xcks

Forces use of an XCKS checksums’ file whatever its extension.

Cannot be set together with the --zxcks option.

-Z, --zxcks

Forces use of a ZXCKS checksums’ file whatever its extension.

Cannot be set together with the --xcks option.

-b, --basedir arg
Replaces the base directory of the (Z)XCKS checksums’ file by arg.

Creating a (Z)XCKS file

-c, --create arg

Creates a (Z)XCKS checksums’ file to a file or to stdout (-).

Defaults to -.

Without the --basedir option the paths of the read files will be writen in the (Z)XCKS checksums’ file relative to the path of arg (or the current directory if arg is -).

-r, --xcks-version arg

Sets the version of XCKS specification of the (Z)XCKS checksums’ file to create.

In this version of xcks, the only known version is 1.0.0.

Defaults to the last known version of XCKS specification.

-z, --compression arg

Sets compression level (for ZXCKS checksums’ file only).

Valid values are integers from 1 (faster compression) to 9 (better compression).

-a, --algorithms arg

Sets the list of algorithms to compute.

arg is a list of names of algorithm separated by a comma (,) and one or more spaces.

Cannot be set together with the --profile option.

-p, --profile arg

Sets a profile of algorithms to compute.

Profiles are stored in the xcks’ configuration file (see the FILES section).

Cannot be set together with the --algorithms option.

--write-file-sizes boolean_arg
Writes the size of files in the (Z)XCKS checksums’ file.
--write-file-date boolean_arg
Writes the last modification date/time of files in the (Z)XCKS checksums’ file.
--abort-on-first-error boolean_arg
Aborts on the first non-fatal error (for example a file that cannot be read).
-O, --overwrite boolean_arg
Tells xcks to overwrite the specified (Z)XCKS checksums’ file for the --create option if it not ends by .xcks or .zxcks, or if it is not stdout (-).

Verifing a (Z)XCKS file

-v, --verify arg

Verifies a (Z)XCKS checksums’ file from a file or stdin (-).

Without the --basedir option the paths of the read files will be relative to the path of arg (or the current directory if arg is -).

--read-before boolean_arg

Reads the (Z)XCKS before verifying the checksums.

The default behaviour is to start to verify files as they are read from the (Z)XCKS file.

Profiles

--list-profiles

Lists the known profiles (list of algorithms of checksums).

Profiles are stored in the xcks’ configuration file (see the FILES section).

If the --wordiness option is set to values or more, the list of valid algorithms per version of XCKS specification is also shown.

If the --wordiness option is set to chatterbox the list of known algorithms with their alternative names is also shown.

EXIT STATUS

0 On success.
1 On bad command line.
2 On error while reading the (Z)XCKS file.
3 On error while verifying a file.
6 On error while writing the (Z)XCKS file.
7 On error while calculating checksums.

FILES

xcks uses two configuration files to set some default parameters: one global and one local (per user). These two files can specify the same set of options.

First the global file is read (if found), and the local one is read (if found).

The priority to set the options is (from to lower to the higher):

An example of configuration file can be found in /usr/share/doc/xcks/xcksrc.sample (change /usr with the prefix of the xcks installation).

Unix systems

Global configuration file

/etc/xcksrc
Default location of the global configuration file.

Local (per user) configuration file

The first found file in this order:

Windows systems

Global configuration file

%ALLUSERSPROFILE%\xcks\etc\xcks.ini
Default location of the global configuration file (%ALLUSERSPROFILE% is also designated by %ProgramData% or %SystemDrive%\ProgramData).

Local (per user) configuration file

The first found file in this order:

ENVIRONNEMENT

XCKSRC
The full file path of the local (per user) configuration file.

BUGS

The current version of xcks doesn’t handle the full range of the ISO 8601 date/time standard. It only reads and writes local date/time without any support of time zone designators.

EXAMPLES

Verify checksums from a XCKS file:
xcks foo.xcks
Verify checksums from a ZXCKS stream from the output of another command:
cat foo.zxcks > xcks -Z
Verify checksums from a XCKS stream from the output of another command:
zcat foo.zxcks > xcks
Verify checksums from a ZXCKS file and rebase the checksums’ file to the current directory (reads the ZXCKS file before starting to verify checksums):
xcks -b . --read-before -v sums/foo.zxcks
Create a XCKS stream to stdout with the CRC-32 and SHA-1 checksums of ‘foo.txt’:
xcks -c - -a "CRC-32, SHA-1" foo.txt | tee foo.xcks
Create a ZXCKS stream to stdout with the MD5 and Whirlpool checksums of ‘foo.txt’:
xcks -c -Z -a "MD5, Whirlpool" foo.txt | zcat
Create a XCKS file with the BLAKE3 and CRC-64 checksums of ‘joker.c’, ‘batman.o’ and ‘pangolin.bin’ rebasing the XCKS file to the current direcory:
xcks -c sums/foo.xcks -a "BLAKE3,CRC-64" -b . joker.c batman.o pangolin.bin
Create a ZXCKS file with the ‘Modern’ profile for checksums of ‘poison_ivy.c’, ‘harley_quinn.c’ and ‘catwoman.c’ (assuming the ‘Modern’ profile exists in a configuration file of xcks):

xcks -c sums/foo.zxcks -p "Modern" poison_ivy.c harley_quinn.c catwoman.c

Note that in the created ZXCKS file, the paths of ‘poison_ivy.c’, ‘harley_quinn.c’ and ‘catwoman.c’ will be ‘../poison_ivy.c’, ‘../harley_quinn.c’ and ‘../catwoman.c’.

Create a XCKS file with the SHA3-512 checksums of ‘d'artagnan.txt’, ‘athos.txt’, ‘porthos.txt’, ‘aramis.txt’ and all the files in the ‘richelieu's agents’ directory and subdirectories:
xcks -c musketeers.xcks -a SHA3-512 "d'artagnan.txt" athos.txt porthos.txt aramis.txt "richelieu's agents"
Create a XCKS file with the CRC-32 checksums of ‘-foo.txt’:
xcks -c foo.xcks -a CRC-32 -- -foo.txt

SEE ALSO

GNU Coreutils’ md5sum(1), sha1sum(1), sha224sum(1), sha256sum(1), sha384sum(1), sha512sum(1)

cksfv(1)