.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.14
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  | will give a
.\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
.\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
.\" expand to `' in nroff, nothing in troff, for use with C<>.
.tr \(*W-|\(bv\*(Tr
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "XMD5SUM 1"
.TH XMD5SUM 1 "2004-12-10" "Scripts" "User Commands"
.SH "NAME"
xmd5sum \- Extended generation and checking of MD5 checksums
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
xmd5sum [\fB\-\-generate\fR] [\fB\-\-binary\fR | \fB\-\-text\fR] [\fB\-\-recursive\fR]
[\fB\-\-output\fR \fIoutput\fR] [\fIfile\fR ...]
.PP
xmd5sum [\fB\-\-status\fR | \fB\-\-quiet\fR | \fB\-\-verbose\fR] [\fB\-\-warn\fR] \fB\-\-check\fR
[\fIsum\fR]
.PP
xmd5sum [\fB\-\-help\fR] [\fB\-\-version\fR]
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBxmd5sum\fR generates or checks 128\-bit \s-1MD5\s0 checksums for a series of
files or directories.  It is essentially an extended version of the
standard \fImd5sum\fR\|(1) program: if a directory name is passed, all files in
that directory are processed; if \fB\-\-recursive\fR is given, directories
below the specified directory are examined as well.
.SH "OPTIONS"
.IX Header "OPTIONS"
The following options are mutually exclusive; only one of these options
should be specified for a given \fBxmd5sum\fR invocation:
.IP "\fB\-\-generate\fR" 4
.IX Item "--generate"
Generate \s-1MD5\s0 checksums for each file \fIfile\fR listed following the
command-line options.  If \fIfile\fR is a directory, \fBxmd5sum\fR generates
\&\s-1MD5\s0 checksums for each file in that directory.  If \fB\-\-recursive\fR is
specified, subdirectories found in \fIfile\fR will also be processed in a
recursive fashion.  \fB\-\-generate\fR is the default mode and does not need to
be specified explicitly.
.IP "\fB\-c\fR, \fB\-\-check\fR" 4
.IX Item "-c, --check"
Read a list of filenames and previously-generated \s-1MD5\s0 checksums from the
file \fIsum\fR (standard input if \fIsum\fR is \fB\-\fR or is not specified) and
check whether the actual files so named match the \s-1MD5\s0 checksum data.
.Sp
The input file \fIsum\fR is usually generated by a previous run of
\&\fBxmd5sum\fR; each line in this file has one of the following two formats:
.Sp
.Vb 2
\&    checksum  filename
\&    checksum *filename
.Ve
.Sp
The first format indicates a text file; the second (with a literal \f(CW\*(C`*\*(C'\fR
character) a binary file (see \fB\-\-binary\fR and \fB\-\-text\fR for more
information on the difference between the two).  The checksum is a
32\-character hexadecimal string.
.Sp
The output from running \fBxmd5sum\fR with \fB\-\-check\fR depends on the
\&\fB\-\-status\fR, \fB\-\-quiet\fR, \fB\-\-verbose\fR and \fB\-\-warn\fR options.  The program
exits with non-zero status if any file does not match the corresponding
\&\s-1MD5\s0 checksum data (or if there were any problems accessing the file);
otherwise, it exits successfully.
.IP "\fB\-h\fR, \fB\-\-help\fR" 4
.IX Item "-h, --help"
Print a usage message listing all of the available options, then exit
successfully.
.IP "\fB\-V\fR, \fB\-\-version\fR" 4
.IX Item "-V, --version"
Print the program's version number and copyright information, then exit
successfully.
.PP
The following four options are only useful when generating checksums:
.IP "\fB\-b\fR, \fB\-\-binary\fR" 4
.IX Item "-b, --binary"
Treat all files listed on the command line as binary, for systems which
distinguish between binary and text files (that is, for systems that have
different internal and external representations of certain text
characters, such as for the end-of-line marker).  On systems where there
is no difference between binary and text mode, the only practical effect
of this option is to prepend a \f(CW\*(C`*\*(C'\fR character to the filenames listed in
the output.  This option is the default on Microsoft Windows and \s-1MS\-DOS\s0.
.IP "\fB\-t\fR, \fB\-\-text\fR" 4
.IX Item "-t, --text"
Treat all files listed on the command line as text.  This option is the
opposite of \fB\-\-binary\fR and is the default on most systems.
.IP "\fB\-r\fR, \fB\-R\fR, \fB\-\-recursive\fR" 4
.IX Item "-r, -R, --recursive"
Process any directories listed on the command line recursively.  In other
words, if a listed directory has subdirectories of its own, those
subdirectories (and \fItheir\fR subdirectories, and so on) will also be
processed.
.IP "\fB\-o\fR \fIoutput\fR, \fB\-\-output\fR \fIoutput\fR" 4
.IX Item "-o output, --output output"
Send the output of \fBxmd5sum\fR to the file \fIoutput\fR after \fIall\fR of the
\&\s-1MD5\s0 checksums have been generated.
.Sp
\&\fBWarning:\fR If \fIoutput\fR exists when \fBxmd5sum\fR is run (and is an
ordinary file), \fIoutput\fR is removed \fIbefore\fR any checksums are
generated.  This prevents the file \fIoutput\fR from being treated as one of
the files to be checksummed.  However, it also means that if \fBxmd5sum\fR is
interrupted, no output file will be generated at all, and the original
file will have been deleted.
.PP
The following four options are only useful when validating (checking)
previously-generated \s-1MD5\s0 checksums; the first three are mutually
exclusive:
.IP "\fB\-\-status\fR" 4
.IX Item "--status"
Do not print anything to standard output or standard error whether a file
matches its previously-generated \s-1MD5\s0 checksum data or not.  Instead,
simply return a successful (zero) exit status if all files correctly
validated, or a non-zero exit code if at least one file failed its check.
.Sp
Please note that if a file does not exist or cannot be opened for reading,
a warning is still printed to standard error.
.IP "\fB\-q\fR, \fB\-\-quiet\fR" 4
.IX Item "-q, --quiet"
Do not print anything to standard output for files that correctly
validated.  Files that fail the check are listed on standard error with
the message \f(CW\*(C`MD5 check failed\*(C'\fR.
.IP "\fB\-v\fR, \fB\-\-verbose\fR" 4
.IX Item "-v, --verbose"
Print each filename checked, along with its checksum status, to standard
output.  If a file correctly validated against its previously-generated
\&\s-1MD5\s0 checksum, \f(CW\*(C`OK\*(C'\fR is printed; otherwise, \f(CW\*(C`FAILED\*(C'\fR is printed.  If a
file fails the \s-1MD5\s0 check, a warning is also sent to standard error with
the message \f(CW\*(C`MD5 check failed\*(C'\fR.
.IP "\fB\-w\fR, \fB\-\-warn\fR" 4
.IX Item "-w, --warn"
Print a warning to standard output for any line in the checksum file
\&\fIsum\fR that is improperly formatted (does not match the format listed
under the \fB\-\-check\fR option).
.PP
If no filenames are specified on the command line for \fB\-\-generate\fR,
standard input is used instead.  The filename \fI\-\fR also represents
standard input.
.PP
If conflicting options are specified on the command line, the last option
seen takes precedence.
.SH "RETURN VALUE"
.IX Header "RETURN VALUE"
\&\fBxmd5sum\fR returns a successful (zero) exit status if all files could be
read and/or validated.  If a file or directory could not be read, or if a
file did not match its previously-generated \s-1MD5\s0 checksum, a non-zero exit
code is returned.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
To generate the \s-1MD5\s0 checksum for any empty file \fIempty\fR:
.PP
.Vb 2
\&    cp /dev/null empty
\&    xmd5sum empty
.Ve
.PP
The output will be:
.PP
.Vb 1
\&    d41d8cd98f00b204e9800998ecf8427e  empty
.Ve
.PP
To generate \s-1MD5\s0 checksums for all files in the current directory, with
output being put in a file \fImd5sum\fR in the same directory:
.PP
.Vb 1
\&    xmd5sum -o md5sum .
.Ve
.PP
(This example is useful for generating \s-1MD5\s0 checksum files for CD\-ROMs).
.PP
To check a previously-generated \fImd5sum\fR file against the current
versions of the files:
.PP
.Vb 1
\&    xmd5sum -c md5sum
.Ve
.SH "FEEDBACK"
.IX Header "FEEDBACK"
Your comments, suggestions, corrections and enhancements are always warmly
welcomed!  Please send these to:
.PP
.Vb 5
\&    Postal:   John Zaitseff,
\&              The ZAP Group,
\&              Unit 6, 116 Woodburn Road,
\&              Berala, NSW, 2141,
\&              Australia
.Ve
.PP
.Vb 2
\&    E-mail:   J.Zaitseff@zap.org.au
\&    Web:      http://www.zap.org.au/software/utils/scripts/
.Ve
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (C) 2004, John Zaitseff.
.PP
This program, including associated files, is free software.  You may
distribute it and/or modify it under the terms of the \s-1GNU\s0 General Public
License as published by the Free Software Foundation; either Version 2 of
the license, or (at your option) any later version.
.PP
This program is distributed in the hope that it will be useful, but
\&\s-1WITHOUT\s0 \s-1ANY\s0 \s-1WARRANTY\s0; without even the implied warranty of \s-1MERCHANTABILITY\s0
or \s-1FITNESS\s0 \s-1FOR\s0 A \s-1PARTICULAR\s0 \s-1PURPOSE\s0.  See the \s-1GNU\s0 General Public License
for more details.
.PP
You should have received a copy of the \s-1GNU\s0 General Public License along
with this program; if not, write to the Free Software Foundation, Inc.,
59 Temple Place, Suite 330, Boston, \s-1MA\s0 02111\-1307 \s-1USA\s0
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fImd5sum\fR\|(1)
.PP
Home page for various scripts on the \s-1ZAP\s0 Group server:
http://www.zap.org.au/software/utils/scripts/