Release 2.1.4.

[u/mdw/catacomb] / hashsum.1

diff --git a/hashsum.1 b/hashsum.1
index f0bd831..3bde5e5 100644 (file)
--- a/hashsum.1
+++ b/hashsum.1
@@ -12,7 +12,7 @@
 hashsum \- compute and verify cryptographic checksums of files
 .SH SYNOPSIS
 .B hashsum
-.RB [ \-f0ecbpv ]
+.RB [ \-f0ecbjpv ]
 .RB [ \-a
 .IR algorithm ]
 .RB [ \-E
@@ -26,10 +26,12 @@ files.  A number of hashing algorithms are available.
 .PP
 The
 .B hashsum
-program's options and output are designed to be upwardly compatible with
-the GNU
+program's options and output were originally designed to be upwardly
+compatible with the GNU
 .BR md5sum (1)
-program.
+program, but the two have diverged somewhat.  See the
+.B "COMPATIBILITY NOTES"
+section of this manual for details.
 .PP
 Usually,
 .B hashsum
@@ -117,6 +119,14 @@ the hash list is authentic (e.g., it has been digitally signed, or
 obtained via some secure medium), this provides strong assurance that
 the files listed have not been tampered with.
 .TP
+.B "\-j, \-\-junk"
+Report files whose hashes have not been checked.  This is most useful in
+conjunction with
+.RB ` \-c ',
+though it's valid without.  The program merely prints warnings about
+junk files when computing hashes, but will exit nonzero if any are found
+when checking them.
+.TP
 .B "\-b, \-\-binary"
 Assume that the files to be hashed are binary files.  This doesn't make
 any difference in Unix systems, although it might on other platforms
@@ -146,7 +156,7 @@ A
 .I directive
 begins with a hash
 .RB (` # ')
-character.  Two directives are currently understood:
+character.  These directives are currently understood:
 .TP
 .BI "#hash " alg
 Subsequent hashes in this file were generated using the algorithm
@@ -295,6 +305,49 @@ option,
 will emit a
 .RB ` #hash '
 directive in its output.
+.SH "COMPATIBILITY NOTES"
+Once upon a time, there was only the
+.BR md5sum (1)
+utility.  As its name suggested, it calculated MD5 hashes of files.  MD5
+was shown to be weak, so the author wrote
+.B hashsum
+to do the same job with other, hopefully stronger, hash functions.  The
+original
+.B hashsum
+program tried hard to be compatible with GNU
+.BR md5sum (1),
+but the latter has itself changed in incompatible ways since then;
+.B hashsum
+has intentionally not changed to match.
+.PP
+The following
+.B hashsum
+features are not found in the GNU Coreutils hashing utilities.
+.hP
+Filename escaping (the
+.B \-e
+option).
+.hP
+Magic comment lines in hash data to indicate algorithm selection, hash
+encoding, and filename escaping.
+.hP
+Base-64 and Base-32 output.
+.PP
+Other differences are as follows.
+.hP
+Originally, if GNU
+.B md5sum
+was invoked without any filename arguments, it would print only the hash
+of its stdin to stdout, which was very convenient for scripts which
+manipulate hashes in nontrivial ways.  This behaviour was later changed,
+and now the GNU Coreutils hashing utilities always print a filename or
+.RB ` \- '
+after the hash.  The
+.B hashsum
+program follows the original
+.B md5sum
+behaviour, and doesn't print a filename if no files were listed on the
+command line.
 .SH "SEE ALSO"
 .BR md5sum (1),
 .BR dsig (1),