DragonFly On-Line Manual Pages

TTHSUM(1)                        User Commands                       TTHSUM(1)

NAME
       tthsum - generates or checks TTH message digests

SYNOPSIS
       tthsum [-bhmpvVw] [-c [file]] | [file...]

DESCRIPTION
       tthsum generates or checks TTH checksums (roots of the Tiger/THEX hash
       tree).  The Merkle Hash Tree, invented by Ralph Merkle, is a hash
       construct that exhibits desirable properties for verifying the
       integrity of files and file subranges in an incremental or out-of-order
       fashion.  tthsum uses the Tiger hash algorithm, by Ross Anderson and
       Eli Biham, for both the internal and the leaf nodes.

       The specification of the THEX algorithm is at:
        .  http://tthsum.devs.nu/draft-jchapweske-thex-02.html

       The specification of the Tiger hash algorithm is at:
        .  http://www.cs.technion.ac.il/~biham/Reports/Tiger/

       Normally tthsum generates checksums of all files given to it as
       parameters and prints the checksums followed by the filenames. If,
       however, -c is specified, only one filename parameter is allowed. This
       file should contain checksums and filenames to which these checksums
       refer, and the files listed in that file are checked against the
       checksums listed there. See option -c for more information.

       If no file is specified data will be read from standard input.

   OPTIONS
       -b     An md5sum compatibility option. It does absolutely nothing.
              (md5sum uses -b to treat binary files differently from texts
              files.)

       -c     Check tthsum of all files listed in file against the checksum
              listed in the same file. The actual format of that file is the
              same as output of tthsum.  That is, each line in the file
              describes a file. A line looks like:

              <TTH CHECKSUM>  <FILENAME>

              So, for example, if a file were created and its message digest
              calculated like so:

              echo foo > tth-test-file; tthsum tth-test-file

              tthsum would report:

              A2MPPCGS5CPJV6AOAP37ICDCFV3WYU7PBREC6FY  tth-test-file

              See NOTES for more information on the digest file format.

       -m     Use mmap(2) instead of read(2) to read the contents of the files
              to hash. Normally, using read is cheaper. This all depends on
              system load, I/O speed, CPU speed, L1 and/or L2 cache size and
              whatnot.

       -p     Show the progress. Print the percentage of completeness while
              hashing on standard error. Prints file position instead of
              percentage when the file size is unknown.

       -v     Be verbose. Print filenames when checking (with -c).

       -w     Warn on improperly formatted lines when checking (with -c).

       -h, -V Print a small help text or the version, respectively, on
              standard out.  If an unknown combination of options is
              encountered, the small help is printed on standard error and
              tthsum will return non-zero.

RETURN VALUE
       tthsum returns 0 if no error occurred or, when checking a digest, if at
       least one line is formatted properly and the TTHs of all properly
       formatted lines match.  tthsum returns 2 if an unknown combination of
       options is encountered.  In all other cases will tthsum return 1.

NOTES
       tthsum intentionally uses an interface identical to md5sum.

       tthsum uses BASE32 encoding consisting of the following characters:
       ABCDEFGHIJKLMNOPQRSTUVWXYZ234567.  It will accept lower case letters in
       the digest input as well.

       tthsum does not accept long options such as --help.

       A digest file format line looks like: <BASE32><SPACES><FILENAME><EOL>.
       BASE32 is a 39 character long BASE32 encoded string.  SPACES is a set
       of two spaces (0x20).  FILENAME is the name of the file, encoded in
       UTF8 and with all control characters (those below 0x20) encoded as \xNN
       or \C C-style escapes. (The backslash is escaped as \\ as well. On
       Windows, backslashes in paths will be translated to slashes for
       compatibility with real operating systems.)  EOL may be CRLF (\r\n),
       just plain LF (\n) or even nothing at end-of-file.

       If you see warnings about an improper locale setup, check your LANG
       and/or LC_CTYPE environment variables.  If these are not set properly,
       tthsum cannot represent non-ASCII characters (those above 0x7F) in
       UTF8. See locale(1) for more information or try to set LC_CTYPE to e.g.
       "en_US".

REPORTING BUGS
       Report bugs to <walter+tthsum@wjd.nu>.

COPYRIGHT
       Copyright (C) 2009 Walter Doekes.  License GPLv3+: GNU GPL version 3 or
       later <http://gnu.org/licenses/gpl.html>
       This is free software: you are free to change and redistribute it.
       There is NO WARRANTY, to the extent permitted by law.

AUTHOR
       tthsum and this manpage were written by Walter Doekes
       (walter+tthsum@wjd.nu).  The hashing code was copied directly from
       DC++, an open source peer-to-peer file sharing program by Jacek Sieka
       (jacek@creatio.se) who had based the hashing code on the one used in
       BCDC++ (a modified DC++) by Dustin Brody (blackclaw@parsoma.net).
       After version 1.1.0, the hashing code from the Tiger hash authors is
       used instead, to support big endian architectures and to remove the
       need for C++ compilers and libraries.  The md5sum manpage, written by
       Juho Vuori (javuori@cc.helsinki.fi), was used as a template. This
       manpage was proofread by Dustin Brody.

SEE ALSO
       cksfv(1), md5sum(1), sha1sum(1)

tthsum version 1.3.2               Dec 2009                          TTHSUM(1)