1 @c This is part of the paxutils manual.
2 @c Copyright (C) 2005, 2007, 2014 Free Software Foundation, Inc.
3 @c Written by Sergey Poznyakoff
4 @c This file is distributed under GFDL 1.1 or any later version
5 @c published by the Free Software Foundation.
7 A @dfn{snapshot file} (or @dfn{directory file}) is created during
8 incremental backups (@pxref{Incremental Dumps}). It
9 contains the status of the file system at the time of the dump and is
10 used to determine which files were modified since the last backup.
12 @GNUTAR{} version @value{VERSION} supports three snapshot file
13 formats. The first format, called @dfn{format 0}, is the one used by
14 @GNUTAR{} versions up to and including 1.15.1. The second format, called
15 @dfn{format 1} is an extended version of this format, that contains more
16 metadata and allows for further extensions. It was used by alpha release
17 version 1.15.90. For alpha version 1.15.91 and stable releases
18 version 1.16 up through @value{VERSION}, the @dfn{format 2} is used.
20 @GNUTAR{} is able to read all three formats, but will create
21 snapshots only in format 2.
23 This appendix describes all three formats in detail.
26 @cindex format 0, snapshot file
27 @cindex snapshot file, format 0
29 @samp{Format 0} snapshot file begins with a line containing a
30 decimal number that represents a @acronym{UNIX} timestamp of the
31 beginning of the last archivation. This line is followed by directory
32 metadata descriptions, one per line. Each description has the
36 [@var{nfs}]@var{dev} @var{inode} @var{name}
44 A single plus character (@samp{+}), if this directory is located on
45 an @acronym{NFS}-mounted partition, otherwise empty.
47 (That is, for non-NFS directories, the first character on the
48 description line contains the start of the @var{dev} field.)
51 Device number of the directory;
54 I-node number of the directory;
57 Name of the directory. Any special characters (white-space,
58 backslashes, etc.) are quoted.
61 @cindex format 1, snapshot file
62 @cindex snapshot file, format 1
64 @samp{Format 1} snapshot file begins with a line specifying the
65 format of the file. This line has the following structure:
68 @samp{GNU tar-}@var{tar-version}@samp{-}@var{incr-format-version}
72 where @var{tar-version} is the version number of @GNUTAR{}
73 implementation that created this snapshot, and
74 @var{incr-format-version} is the version number of the snapshot format
75 (in this case @samp{1}).
77 Next line contains two decimal numbers, representing the
78 time of the last backup. First number is the number of seconds, the
79 second one is the number of nanoseconds, since the beginning of the
82 Lines that follow contain directory metadata, one line per
83 directory. Each line is formatted as follows:
86 [@var{nfs}]@var{mtime-sec} @var{mtime-nsec} @var{dev} @var{inode} @var{name}
90 where @var{mtime-sec} and @var{mtime-nsec} represent last
91 modification time of this directory with nanosecond precision;
92 @var{nfs}, @var{dev}, @var{inode} and @var{name} have the same meaning
93 as with @samp{format 0}.
95 @cindex format 2, snapshot file
96 @cindex snapshot file, format 2
98 @samp{Format 2} snapshot file begins with a format identifier, as described for
102 GNU tar-@value{VERSION}-2
105 This line is followed by newline. Rest of file consists of
106 records, separated by null (@acronym{ASCII} 0)
107 characters. Thus, in contrast to the previous formats, format 2
108 snapshot is a binary file.
110 First two records are decimal integers, representing the
111 time of the last backup. First number is the number of seconds, the
112 second one is the number of nanoseconds, since the beginning of the
113 epoch. These are followed by arbitrary number of directory records.
115 Each @dfn{directory record} contains a set of metadata describing a
116 particular directory. Parts of a directory record are delimited with
117 @acronym{ASCII} 0 characters. The following table describes each
118 part. The @dfn{Number} type in this table stands for a decimal integer
119 in @acronym{ASCII} notation. (Negative values are preceeded with a "-"
120 character, while positive values have no leading punctuation.)
122 @multitable @columnfractions 0.25 0.15 0.6
123 @headitem Field @tab Type @tab Description
124 @item nfs @tab Character @tab @samp{1} if the directory is located on
125 an @acronym{NFS}-mounted partition, or @samp{0} otherwise;
126 @item timestamp_sec @tab Number @tab Modification time, seconds;
127 @item timestamp_nsec @tab Number @tab Modification time, nanoseconds;
128 @item dev @tab Number @tab Device number;
129 @item ino @tab Number @tab I-node number;
130 @item name @tab String @tab Directory name; in contrast to the
131 previous versions it is not quoted;
132 @item contents @tab Dumpdir @tab Contents of the directory;
133 @xref{Dumpdir}, for a description of its format.
137 Dumpdirs stored in snapshot files contain only records of types
138 @samp{Y}, @samp{N} and @samp{D}.
140 @cindex snapshot file field ranges
141 @opindex show-snapshot-field-ranges
142 The specific range of values allowed in each of the @dfn{Number} fields
143 depends on the underlying C datatypes as determined when @command{tar}
144 is compiled. To see the specific ranges allowed for a particular
145 @command{tar} binary, you can use the
146 @option{--show-snapshot-field-ranges} option:
149 $ @kbd{tar --show-shapshot-field-ranges}
150 This tar's snapshot file field ranges are
151 (field name => [ min, max ]):
154 timestamp_sec => [ -9223372036854775808, 9223372036854775807 ],
155 timestamp_nsec => [ 0, 999999999 ],
156 dev => [ 0, 18446744073709551615 ],
157 ino => [ 0, 18446744073709551615 ],
160 (This example is from a GNU/Linux x86_64 system.)
164 @c End of snapshot.texi