1 @c This is part of the paxutils manual.
2 @c Copyright (C) 2005, 2007 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
99 @samp{Format 2} snapshot file begins with a format identifier, as described for
103 GNU tar-@value{VERSION}-2
106 This line is followed by newline. Rest of file consists of
107 records, separated by null (@acronym{ASCII} 0)
108 characters. Thus, in contrast to the previous formats, format 2
109 snapshot is a binary file.
111 First two records are decimal numbers, representing the
112 time of the last backup. First number is the number of seconds, the
113 second one is the number of nanoseconds, since the beginning of the
114 epoch. These are followed by arbitrary number of directory records.
116 Each @dfn{directory record} contains a set of metadata describing a
117 particular directory. Parts of a directory record are delimited with
118 @acronym{ASCII} 0 characters. The following table describes each
119 part. The @dfn{Number} type in this table stands for a decimal number
120 in @acronym{ASCII} notation.
122 @multitable @columnfractions 0.2 0.2 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 mtime-sec @tab Number @tab Modification time, seconds;
127 @item mtime-nano @tab Number @tab Modification time, nanoseconds;
128 @item dev-no @tab Number @tab Device number;
129 @item i-no @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}.
142 @c End of snapshot.texi