Document version 2

doc/snapshot.texi

@@ -1,5 +1,5 @@
 @c This is part of the paxutils manual.
-@c Copyright (C) 2005 Free Software Foundation, Inc.
+@c Copyright (C) 2005, 2007 Free Software Foundation, Inc.
 @c Written by Sergey Poznyakoff
 @c This file is distributed under GFDL 1.1 or any later version
 @c published by the Free Software Foundation.
@@ -9,27 +9,55 @@ incremental backups (@pxref{Incremental Dumps}).  It
 contains the status of the file system at the time of the dump and is
 used to determine which files were modified since the last backup.
 
-  @GNUTAR{} version @value{VERSION} supports two snapshot file
+  @GNUTAR{} version @value{VERSION} supports three snapshot file
 formats.  The first format, called @dfn{format 0}, is the one used by
 @GNUTAR{} versions up to 1.15.1. The second format, called @dfn{format
 1} is an extended version of this format, that contains more metadata
-and allows for further extensions.
+and allows for further extensions. It was used by version
+1.15.1. Starting from version 1.16 and up to @value{VERSION}, the
+@dfn{format 2} is used.
 
+  @GNUTAR{} is able to read all three formats, but will create
+snapshots only in format 2.
+
+  This appendix describes all three formats in detail.
+
+@enumerate 0
+@cindex format 0, snapshot file  
+@cindex snapshot file, format 0
+@item   
   @samp{Format 0} snapshot file begins with a line containing a
-decimal number that represents the UNIX timestamp of the beginning of
-the last archivation. This line is followed by directory metadata
-descriptions, one per line. Each description has the following format:
+decimal number that represents a @acronym{UNIX} timestamp of the
+beginning of the last archivation. This line is followed by directory
+metadata descriptions, one per line. Each description has the
+following format: 
 
 @smallexample
-[@var{nfs}]@var{dev} @var{inode} @var{name}
+@var{nfs}@var{dev} @var{inode} @var{name}
 @end smallexample
 
 @noindent
-where optional @var{nfs} is a single plus character (@samp{+}) if this
-directory is located on an NFS-mounted partition, @var{dev} and
-@var{inode} are the device and inode numbers of the directory, and
-@var{name} is the directory name.
+where:
+
+@table @var
+@item nfs
+A single plus character (@samp{+}), if this directory is located on
+an @acronym{NFS}-mounted partition, or a single space otherwise;
+
+@item dev
+Device number of the directory;
 
+@item inode
+I-node number of the directory;
+
+@item name
+Name of the directory. Any special characters (white-space,
+backslashes, etc.) are quoted.
+@end table
+
+@cindex format 1, snapshot file  
+@cindex snapshot file, format 1
+@item   
   @samp{Format 1} snapshot file begins with a line specifying the
 format of the file. This line has the following structure:
 
@@ -38,28 +66,75 @@ format of the file. This line has the following structure:
 @end smallexample
 
 @noindent
-where @var{tar-version} is the version of @GNUTAR{} implementation
-that created this snapshot, and @var{incr-format-version} is the
-version number of the snapshot format (in this case @samp{1}).
+where @var{tar-version} is the version number of @GNUTAR{}
+implementation that created this snapshot, and
+@var{incr-format-version} is the version number of the snapshot format
+(in this case @samp{1}). 
 
-  The following line contains two decimal numbers, representing the
+  Next line contains two decimal numbers, representing the
 time of the last backup. First number is the number of seconds, the
 second one is the number of nanoseconds, since the beginning of the
 epoch.
 
-  Following lines contain directory metadata, one line per
-directory. The line format is:
+  Lines that follow contain directory metadata, one line per
+directory. Each line is formatted as follows:
 
 @smallexample
 [@var{nfs}]@var{mtime-sec} @var{mtime-nsec} @var{dev} @var{inode} @var{name}
 @end smallexample
 
 @noindent
-where @var{mtime-sec} and @var{mtime-nsec} represent the last
+where @var{mtime-sec} and @var{mtime-nsec} represent last
 modification time of this directory with nanosecond precision;
 @var{nfs}, @var{dev}, @var{inode} and @var{name} have the same meaning
 as with @samp{format 0}.
 
+@cindex format 2, snapshot file  
+@cindex snapshot file, format 2
+@item
+@FIXME{}
+  A snapshot file begins with a format identifier, as described for
+version 1, e.g.:
+
+@smallexample
+GNU tar-@value{VERSION}-2
+@end smallexample
+
+  This line is followed by newline. Rest of file consists of
+records, separated by null (@acronym{ASCII} 0)
+characters. Thus, in contrast to the previous formats, format 2
+snapshot is a binary file.
+
+  First two records are decimal numbers, representing the
+time of the last backup.  First number is the number of seconds, the
+second one is the number of nanoseconds, since the beginning of the
+epoch.  These are followed by arbitrary number of directory records.
+  
+  Each @dfn{directory record} contains a set of metadata describing a
+particular directory.  Parts of a directory record are delimited with
+@acronym{ASCII} 0 characters.  The following table describes each
+part.  The @dfn{Number} type in this table stands for a decimal number
+in @acronym{ASCII} notation.
+
+@multitable @columnfractions 0.2 0.2 0.6
+@headitem Field @tab Type @tab Description
+@item nfs @tab Character @tab @samp{1} if the directory is located on
+an @acronym{NFS}-mounted partition, or @samp{0} otherwise;
+@item mtime-sec @tab Number @tab Modification time, seconds;
+@item mtime-nano @tab Number @tab Modification time, nanoseconds;
+@item dev-no @tab Number @tab Device number;
+@item i-no @tab Number @tab I-node number;
+@item name @tab String @tab Directory name; In contrast to the
+previous versions it is not quoted.
+@item contents @tab Dumpdir @tab Contents of the directory;
+@xref{Dumpdir}, for a description of its format.
+@item 
+@end multitable
+
+  Dumpdirs stored in snapshot files contain only records of types
+@samp{Y}, @samp{N} and @samp{D}.
+
+@end enumerate
 
 @c End of snapshot.texi