X-Git-Url: https://git.dogcows.com/gitweb?p=chaz%2Ftar;a=blobdiff_plain;f=doc%2Fsnapshot.texi;h=f57e55fea008b29b849365a57274e9a0c004055f;hp=5607a08e7409b58b85a3e75565f596edcc74ac9b;hb=45ccda119355a1087450039a250359c1d0de0d08;hpb=0ab5e64ac07d5b0162bf863f4da485d26760a8eb

diff --git a/doc/snapshot.texi b/doc/snapshot.texi
index 5607a08..f57e55f 100644
--- a/doc/snapshot.texi
+++ b/doc/snapshot.texi
@@ -1,5 +1,5 @@
 @c This is part of the paxutils manual.
-@c Copyright (C) 2005, 2007 Free Software Foundation, Inc.
+@c Copyright (C) 2005, 2007, 2014 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.
@@ -11,11 +11,11 @@ used to determine which files were modified since the last backup.
 
   @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. 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{} versions up to and including 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. It was used by alpha release
+version 1.15.90. For alpha version 1.15.91 and stable releases
+version 1.16 up through @value{VERSION}, the @dfn{format 2} is used.
 
   @GNUTAR{} is able to read all three formats, but will create
 snapshots only in format 2.
@@ -33,7 +33,7 @@ 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
@@ -42,7 +42,10 @@ 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;
+an @acronym{NFS}-mounted partition, otherwise empty.  
+
+(That is, for non-NFS directories, the first character on the
+description line contains the start of the @var{dev} field.)
 
 @item dev
 Device number of the directory;
@@ -91,7 +94,6 @@ as with @samp{format 0}.
 
 @cindex format 2, snapshot file
 @cindex snapshot file, format 2
-@FIXME{}
 @item
   @samp{Format 2} snapshot file begins with a format identifier, as described for
 version 1, e.g.:
@@ -105,7 +107,7 @@ 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
+  First two records are decimal integers, 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.
@@ -113,17 +115,18 @@ 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.
+part.  The @dfn{Number} type in this table stands for a decimal integer
+in @acronym{ASCII} notation.  (Negative values are preceeded with a "-"
+character, while positive values have no leading punctuation.)
 
-@multitable @columnfractions 0.2 0.2 0.6
+@multitable @columnfractions 0.25 0.15 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 timestamp_sec @tab Number @tab Modification time, seconds;
+@item timestamp_nsec @tab Number @tab Modification time, nanoseconds;
+@item dev @tab Number @tab Device number;
+@item ino @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;
@@ -134,6 +137,28 @@ previous versions it is not quoted;
   Dumpdirs stored in snapshot files contain only records of types
 @samp{Y}, @samp{N} and @samp{D}.
 
+@cindex snapshot file field ranges
+@opindex show-snapshot-field-ranges
+The specific range of values allowed in each of the @dfn{Number} fields
+depends on the underlying C datatypes as determined when @command{tar}
+is compiled.  To see the specific ranges allowed for a particular
+@command{tar} binary, you can use the
+@option{--show-snapshot-field-ranges} option:
+
+@smallexample
+$ @kbd{tar --show-shapshot-field-ranges}
+This tar's snapshot file field ranges are
+   (field name      => [ min, max ]):
+
+    nfs             => [ 0, 1 ],
+    timestamp_sec   => [ -9223372036854775808, 9223372036854775807 ],
+    timestamp_nsec  => [ 0, 999999999 ],
+    dev             => [ 0, 18446744073709551615 ],
+    ino             => [ 0, 18446744073709551615 ],
+@end smallexample
+
+(This example is from a GNU/Linux x86_64 system.)
+
 @end enumerate
 
 @c End of snapshot.texi