.\" $Header: /home/ahuxley/dev/active/fad/man/RCS/faddiff.1,v 1.25 2002/01/03 12:47:06 ahuxley Exp $
.\"
.TH FADDIFF 1 "3 January 2002"
.SH NAME
faddiff \- Report Differences Between Two File Attribute Databases
.br
.\" we don't need a .br/.ne 5 here since there
.\" isn't any chance really, that we're already
.\" anywhere near the end of the first page.
.\"
.SH SYNOPSIS
.B faddiff
[
.B \-v
|
.B \-u
|
.B \-g
|
.B \-m
|
.B \-d
.I level
] [
.B \-o
.I outfile
]
.I file1 file2
.br
.B "faddiff -V"
.br
.\"
.\" we don't need a .br/.ne 5 here since there
.\" isn't any chance really, that we're already
.\" anywhere near the end of the first page.
.\"
.SH DESCRIPTION
This man page documents 
.I faddiff 
version MARKER_PATCHLEVEL.
.PP
.I Faddiff
is a Perl 
(see
.I perl\fR(1))
script which reports differences between two FAD files (see 
.I fad\fR(5)),
such as are generated by 
.I mkfad\fR(1).
The input files must be specified on the command line, though
either one of them may be replaced with 
.B \-\fR,
in which case
.I faddiff
reads from the standard input. By default
.I faddiff 
writes the resulting difference list to the standard output.
.PP 
All differences between the state of an individual file in
the two FAD files are reported on one line. The format of
of such a line is:
.IP
.nf
\fIpath\fR: \fIchangetype\fR(\fIoldvalue\fR -> \fInewvalue\fR), ...
.fi
.PP
.I path
represents the path of the file that has changed. 
.I changetype
may be one of the following:
.TP 15
.B added
.I path
is mentioned in the second FAD file only. The brackets are empty.
.TP
.B deleted
.I path
is mentioned in the first FAD file only. The brackets are empty.
.TP
.B mode
.I path
has different permissions in the two FAD files. Bracketed
are the permissions, expressed as octal numbers, in the first file and
then in the second.
.TP
.B owner
.I path 
has different a different owner in the two FAD files. Bracketed
are the numeric user ids in the first file and
then in the second.
.TP
.B group
.I path 
has different a different group in the two FAD files. Bracketed
are the numeric group ids in the first file and
then in the second.
.TP
.B links
.I path
has a different set of hard links in the two FAD files. Bracketed
are the names of the other hard links in the first file and then
in the second.
.TP
.B type
.I path
has changed type. This indicates that 
.I path
has been deleted and subsequently recreated as a file-system object
of a different type. Bracketed are the types in the first file and
then in the second file. The types are represented by the following
characters:
.RS 20
.TP 5
.B f
file
.TP 
.B d
directory
.TP
.B p
pipe
.TP
.B l
symbolic link
.TP
.B b
block device
.TP
.B c
character device
.TP
.B s
socket
.RE
.TP
.B checksum
.I path
is a file whose contents is different as gauged by the 
.I path\fR's
32 bit checksum. Bracketed are the checksums in the first file and then 
in the second.
.TP
.B linked_to
.I path 
is a symbolic link which has different destinations in
the two FAD files. Bracketed are the symbolic link destinations in the first 
file and then in the second.
.TP
.B major/minor
.I path
is a special device file which has different major or minor numbers in
the two FAD files. Bracketed are the combined major and minor numbers in
the first file and then in the second.
.PP
.I Faddiff
and 
.I mkfad\fR(1) 
were designed as software package management tools,
similar to the commands 
.I mkpdf\fR(1m)
and
.I pdfdiff\fR(1m)
under HP-UX.
.PP 
.I Faddiff
can read and write plain files or files compressed with 
either
.I compress\fR(1)
or 
.I gzip\fR(1). 
All that is necessary to use this feature is to specify
file names with suitable extensions.
.br
.ne 5
.SH OPTIONS
.\"  This indents everything after the next line by 25 some-things.
.TP 25
.B \-V
Print the version number and exit.
.TP
.B \-o
Writes the database to 
.I outfile\fR.
The default is to write to standard output.
.TP
.B \-v
Sets the verbosity level to 3.
.TP
.B \-d \fIlevel
Sets the verbosity level to
.I level\fR.
.TP
.B \-u
Ignores changes of owner/user.
.TP
.B \-g
Ignores changes of group.
.TP
.B \-m
Ignores changes of mode.
.PD
.br
.ne 5
.SH EXAMPLES
The following output shows the results on running
.I faddiff 
on two FAD files. These files were generated with
.I mkfad\fR(1).
In between time, several changes were made to 
indicatively named files.
.IP
.nf
testdir/changedest: linked_to(dest1 -> dest2)
testdir/changegrp: group(79 -> 0)
testdir/changeme: links( -> ./linkedfile), checksum(5233 -> 5300)
testdir/changemin: major/minor(515 -> 772)
testdir/changemytype: type(f -> d)
testdir/changeown: owner(1663 -> 1194)
testdir/changeperm: mode(100600 -> 100755)
testdir/deleteme: deleted()
testdir/fad1: checksum(0 -> 25025)
testdir/fad2: added()
testdir/linkedfile: added()
testdir/newfile: added()
.fi
.br
.ne 5
.SH FILES
See
.I fad\fR(5).
.br
.ne 5
.SH ENVIRONMENT VARIABLES
See
.I fad\fR(5).
.br
.ne 5
.SH DIAGNOSTICS
Only diagnostic messages which are so cryptic that they need to be explained
are explained here.
.PD 0
.TP 25
.B configuration error: wrong version of ...
A possibly incompatible Perl library has been located. This is symptomatic
of a incorrect installation or failure to segregate versions of Perl libraries
used by the FAD suite of programs from versions of the same libraries used by
other programs that are on different release numbers. But see ENVIRONMENT
VARIABLES above.
.TP
.B faddiff: ERROR: only one file can be read from standard input
A maximum of one FAD file can be read from the standard input. This error 
occurs when '-' is specified twice on the command line indicating that both
files should be read from the standard input.
.TP
.B faddiff: ERROR: invalid version or non fad file
One of the specified FAD files does not have a properly formatted header.
.PD
.br
.ne 5
.SH CAVEATS
None.
.br
.ne 5
.SH SEE ALSO
perl(1), fad(5), faddiff(1), mkpdf(1m), pdfdiff(1m),
compress(1), uncompress(1), gzip(1), gunzip(1)
.br
.ne 5
.SH AUTHOR
Alexis Huxley
.br
.ne 5
.SH BUGS
No known bugs.
.PP
Bug reports and queries should be reported to
.B fad-support@danae.demon.co.uk\fR.
.PP
For the latest release of the FAD tools,
visit
.B http://www.danae.demon.co.uk/software/fad/\fR.
.br
.ne 5
.SH COPYRIGHT & DISTRIBUTION POLICY
Copyright (C) 1995-2002 Alexis Huxley
.PP
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU 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 WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.
.PP
You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.