doc/snapshot.texi

   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.
   6
   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.
  11
  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 1.15.1. The second format, called @dfn{format
  15 1} is an extended version of this format, that contains more metadata
  16 and allows for further extensions. It was used by version
  17 1.15.1. Starting from version 1.16 and up to @value{VERSION}, the
  18 @dfn{format 2} is used.
  19
  20   @GNUTAR{} is able to read all three formats, but will create
  21 snapshots only in format 2.
  22
  23   This appendix describes all three formats in detail.
  24
  25 @enumerate 0
  26 @cindex format 0, snapshot file
  27 @cindex snapshot file, format 0
  28 @item
  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
  33 following format:
  34
  35 @smallexample
  36 @var{nfs}@var{dev} @var{inode} @var{name}
  37 @end smallexample
  38
  39 @noindent
  40 where:
  41
  42 @table @var
  43 @item nfs
  44 A single plus character (@samp{+}), if this directory is located on
  45 an @acronym{NFS}-mounted partition, or a single space otherwise;
  46
  47 @item dev
  48 Device number of the directory;
  49
  50 @item inode
  51 I-node number of the directory;
  52
  53 @item name
  54 Name of the directory. Any special characters (white-space,
  55 backslashes, etc.) are quoted.
  56 @end table
  57
  58 @cindex format 1, snapshot file
  59 @cindex snapshot file, format 1
  60 @item
  61   @samp{Format 1} snapshot file begins with a line specifying the
  62 format of the file. This line has the following structure:
  63
  64 @smallexample
  65 @samp{GNU tar-}@var{tar-version}@samp{-}@var{incr-format-version}
  66 @end smallexample
  67
  68 @noindent
  69 where @var{tar-version} is the version number of @GNUTAR{}
  70 implementation that created this snapshot, and
  71 @var{incr-format-version} is the version number of the snapshot format
  72 (in this case @samp{1}).
  73
  74   Next line contains two decimal numbers, representing the
  75 time of the last backup. First number is the number of seconds, the
  76 second one is the number of nanoseconds, since the beginning of the
  77 epoch.
  78
  79   Lines that follow contain directory metadata, one line per
  80 directory. Each line is formatted as follows:
  81
  82 @smallexample
  83 [@var{nfs}]@var{mtime-sec} @var{mtime-nsec} @var{dev} @var{inode} @var{name}
  84 @end smallexample
  85
  86 @noindent
  87 where @var{mtime-sec} and @var{mtime-nsec} represent last
  88 modification time of this directory with nanosecond precision;
  89 @var{nfs}, @var{dev}, @var{inode} and @var{name} have the same meaning
  90 as with @samp{format 0}.
  91
  92 @cindex format 2, snapshot file
  93 @cindex snapshot file, format 2
  94 @FIXME{}
  95 @item
  96   @samp{Format 2} snapshot file begins with a format identifier, as described for
  97 version 1, e.g.:
  98
  99 @smallexample
 100 GNU tar-@value{VERSION}-2
 101 @end smallexample
 102
 103   This line is followed by newline. Rest of file consists of
 104 records, separated by null (@acronym{ASCII} 0)
 105 characters. Thus, in contrast to the previous formats, format 2
 106 snapshot is a binary file.
 107
 108   First two records are decimal numbers, representing the
 109 time of the last backup.  First number is the number of seconds, the
 110 second one is the number of nanoseconds, since the beginning of the
 111 epoch.  These are followed by arbitrary number of directory records.
 112
 113   Each @dfn{directory record} contains a set of metadata describing a
 114 particular directory.  Parts of a directory record are delimited with
 115 @acronym{ASCII} 0 characters.  The following table describes each
 116 part.  The @dfn{Number} type in this table stands for a decimal number
 117 in @acronym{ASCII} notation.
 118
 119 @multitable @columnfractions 0.2 0.2 0.6
 120 @headitem Field @tab Type @tab Description
 121 @item nfs @tab Character @tab @samp{1} if the directory is located on
 122 an @acronym{NFS}-mounted partition, or @samp{0} otherwise;
 123 @item mtime-sec @tab Number @tab Modification time, seconds;
 124 @item mtime-nano @tab Number @tab Modification time, nanoseconds;
 125 @item dev-no @tab Number @tab Device number;
 126 @item i-no @tab Number @tab I-node number;
 127 @item name @tab String @tab Directory name; in contrast to the
 128 previous versions it is not quoted;
 129 @item contents @tab Dumpdir @tab Contents of the directory;
 130 @xref{Dumpdir}, for a description of its format.
 131 @item
 132 @end multitable
 133
 134   Dumpdirs stored in snapshot files contain only records of types
 135 @samp{Y}, @samp{N} and @samp{D}.
 136
 137 @end enumerate
 138
 139 @c End of snapshot.texi