tar: Snapshot Files
1
1 Format of the Incremental Snapshot Files
1 ========================================
1
1 A "snapshot file" (or "directory file") is created during incremental
1 backups (⇒Incremental Dumps). It contains the status of the file
1 system at the time of the dump and is used to determine which files were
1 modified since the last backup.
1
1 GNU 'tar' version 1.30 supports three snapshot file formats. The
1 first format, called "format 0", is the one used by GNU 'tar' versions
1 up to and including 1.15.1. The second format, called "format 1" is an
1 extended version of this format, that contains more metadata and allows
1 for further extensions. It was used by alpha release version 1.15.90.
1 For alpha version 1.15.91 and stable releases version 1.16 up through
1 1.30, the "format 2" is used.
1
1 GNU 'tar' is able to read all three formats, but will create
1 snapshots only in format 2.
1
1 This appendix describes all three formats in detail.
1
1 0. 'Format 0' snapshot file begins with a line containing a decimal
1 number that represents a UNIX timestamp of the beginning of the
1 last archivation. This line is followed by directory metadata
1 descriptions, one per line. Each description has the following
1 format:
1
1 [NFS]DEV INODE NAME
1
1 where:
1
1 NFS
1 A single plus character ('+'), if this directory is located on
1 an NFS-mounted partition, otherwise empty.
1
1 (That is, for non-NFS directories, the first character on the
1 description line contains the start of the DEV field.)
1
1 DEV
1 Device number of the directory;
1
1 INODE
1 I-node number of the directory;
1
1 NAME
1 Name of the directory. Any special characters (white-space,
1 backslashes, etc.) are quoted.
1
1 1. 'Format 1' snapshot file begins with a line specifying the format
1 of the file. This line has the following structure:
1
1 'GNU tar-'TAR-VERSION'-'INCR-FORMAT-VERSION
1
1 where TAR-VERSION is the version number of GNU 'tar' implementation
1 that created this snapshot, and INCR-FORMAT-VERSION is the version
1 number of the snapshot format (in this case '1').
1
1 Next line contains two decimal numbers, representing the time of
1 the last backup. First number is the number of seconds, the second
1 one is the number of nanoseconds, since the beginning of the epoch.
1
1 Lines that follow contain directory metadata, one line per
1 directory. Each line is formatted as follows:
1
1 [NFS]MTIME-SEC MTIME-NSEC DEV INODE NAME
1
1 where MTIME-SEC and MTIME-NSEC represent last modification time of
1 this directory with nanosecond precision; NFS, DEV, INODE and NAME
1 have the same meaning as with 'format 0'.
1
1 2. 'Format 2' snapshot file begins with a format identifier, as
1 described for version 1, e.g.:
1
1 GNU tar-1.30-2
1
1 This line is followed by newline. Rest of file consists of
1 records, separated by null (ASCII 0) characters. Thus, in contrast
1 to the previous formats, format 2 snapshot is a binary file.
1
1 First two records are decimal integers, representing the time of
1 the last backup. First number is the number of seconds, the second
1 one is the number of nanoseconds, since the beginning of the epoch.
1 These are followed by arbitrary number of directory records.
1
1 Each "directory record" contains a set of metadata describing a
1 particular directory. Parts of a directory record are delimited
1 with ASCII 0 characters. The following table describes each part.
1 The "Number" type in this table stands for a decimal integer in
1 ASCII notation. (Negative values are preceded with a "-"
1 character, while positive values have no leading punctuation.)
1
1 Field Type Description
1 ---------------------------------------------------------------------------
1 nfs Character '1' if the directory is located on an
1 NFS-mounted partition, or '0' otherwise;
1 timestamp_sec Number Modification time, seconds;
1 timestamp_nsec Number Modification time, nanoseconds;
1 dev Number Device number;
1 ino Number I-node number;
1 name String Directory name; in contrast to the
1 previous versions it is not quoted;
1 contents Dumpdir Contents of the directory;
1 ⇒Dumpdir, for a description of its
1 format.
1
1 Dumpdirs stored in snapshot files contain only records of types
1 'Y', 'N' and 'D'.
1
1 The specific range of values allowed in each of the "Number" fields
1 depends on the underlying C datatypes as determined when 'tar' is
1 compiled. To see the specific ranges allowed for a particular
1 'tar' binary, you can use the '--show-snapshot-field-ranges'
1 option:
1
1 $ tar --show-shapshot-field-ranges
1 This tar's snapshot file field ranges are
1 (field name => [ min, max ]):
1
1 nfs => [ 0, 1 ],
1 timestamp_sec => [ -9223372036854775808, 9223372036854775807 ],
1 timestamp_nsec => [ 0, 999999999 ],
1 dev => [ 0, 18446744073709551615 ],
1 ino => [ 0, 18446744073709551615 ],
1
1 (This example is from a GNU/Linux x86_64 system.)
1