.\"  $HeadURL$ $LastChangedRevision$
.TH FAD 5 "ADE_APP_TOKEN_RELEASE_DATE_MAN"
.ne 5
.SH NAME
FAD \- File Attribute Database
.br
.SH DESCRIPTION
A FAD
file is a file describing the attributes of a set of filesystem
objects in a format processable by the FAD tools, 
.B mkfad\fR(1),
.B faddiff\fR(1),
.B fadcat\fR(1),
.B fadfixperms\fR(1)
and
.B fadscan\fR(1).
.PP
A FAD file consists of a header section and a body body section.
.PP
The header section consists of lines separated by Unix newlines
(octal 012). Each line consists of words 
separated by spaces (octal 040). The order of lines is as follows:
.pp
.nf
.RS 10
.I magicnumber
.I version-dependent-headers
.B EOH
.fi
.PP
which are:
.RS 10
.TP 25
.I magicnumber
literal text 
.B FaDFiLe
.TP
.I version-dependent-headers
a mixture of mandatory and optional header lines
(described in detail below)
.TP
.B EOH
literal text marking the end of the FAD header
.RE
.PP
The mandatory headers lines are:
.RS 10
.TP 25
.B FAD-Version \fIfad-version\fB
literal text 
.B FAD-Version 
followed by the ASCII representation of the FAD version number with which
the file is compliant (this should be 
.B 4\fR)
.TP
.B Field-Separator \fIfield-separator\fB
literal text
.B Field-Separator
followed by the URI-encoded single character used to separate FAD 
fields within a single FAD record in the main body of the FAD file (see 
.B URI::Escape\fR(3))
.TP
.B Record-Separator \fIrecord-separator\fB
literal text
.B Record-Separator
followed by the URI-encoded single character used to separate FAD 
records in the main body of the FAD file (see 
.B URI::Escape\fR(3))
.TP
.B Unix-Time \fIunix-time\fB
literal text
.B Unix-Time
followed by the number of seconds after 1 January 1970 00:00 at
which the FAD file was created (see
.B time\fR(2)).
.RE
.PP 
Any other header line is considered optional and is ignored. The
FAD tools mentioned above do not write optional headers.
.PP
The body section consists of a single
.B perl\fR(1)
assignment produced by the 
.B Data::Dumper\fR(3perl)
module. 
.br
.ne 5
.SH CAVEATS
Field and record separators in both the header and body of a FAD file
are not currently variable. There should be no need for this anyway.
.PP
FAD files should not be parsed by anything except FAD tools or other tools
based on the FAD library; no guarantee is made that the format will be
kept backwardly compatible.
.br
.ne 5
.SH STANDARDS
This manual page documents the FAD file format level 4 only.
.br
.ne 5
.SH SEE ALSO
mkfad(1), faddiff(1), fadscan(1), fadcat(1), 
fadfixperms(1), perl(1), file(1), find(1), ls(1),
URI::Escape(3perl), Data::Dumper(3perl), sort(1), fad-config(1)
.br
.ne 5
.SH CHANGE HISTORY
FAD file format level 1 was not eight-bit clean, used a single line 
FAD header (#F1), and used character 034 as a field separator.
.PP
FAD file format level 2.00 was eight-bit clean, used a multi-line FAD
header, and used magic number sequence 0106 0106.
.PP
FAD file format level 2.01 used a fixed format header.
.PP
FAD file format level 2.02 introduced
.B Unix-Time 
header and variable order header lines.
.PP
FAD file format level 3 introduced empty inode and device number
fields, and reverted to integer FAD format levels.
.PP
FAD file format level 4 switched to 
.B Data::Dumper\fR(1)
format in order to automatically handle escaping of filenames.
.br
.ne 5
.SH AUTHOR
ADE_APP_TOKEN_AUTHOR_NAME <ADE_APP_TOKEN_AUTHOR_EMAIL>
.br
.ne 5
.SH COPYRIGHT & DISTRIBUTION POLICY
Copyright (C) 1995-ADE_APP_TOKEN_RELEASE_YEAR ADE_APP_TOKEN_AUTHOR_NAME
.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.