Dogcows Code - chaz/tar/blob - 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 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.
  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, otherwise empty.
  46
  47 (That is, for non-NFS directories, the first character on the
  48 description line contains the start of the @var{dev} field.)
  49
  50 @item dev
  51 Device number of the directory;
  52
  53 @item inode
  54 I-node number of the directory;
  55
  56 @item name
  57 Name of the directory. Any special characters (white-space,
  58 backslashes, etc.) are quoted.
  59 @end table
  60
  61 @cindex format 1, snapshot file
  62 @cindex snapshot file, format 1
  63 @item
  64   @samp{Format 1} snapshot file begins with a line specifying the
  65 format of the file. This line has the following structure:
  66
  67 @smallexample
  68 @samp{GNU tar-}@var{tar-version}@samp{-}@var{incr-format-version}
  69 @end smallexample
  70
  71 @noindent
  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}).
  76
  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
  80 epoch.
  81
  82   Lines that follow contain directory metadata, one line per
  83 directory. Each line is formatted as follows:
  84
  85 @smallexample
  86 [@var{nfs}]@var{mtime-sec} @var{mtime-nsec} @var{dev} @var{inode} @var{name}
  87 @end smallexample
  88
  89 @noindent
  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}.
  94
  95 @cindex format 2, snapshot file
  96 @cindex snapshot file, format 2
  97 @FIXME{}
  98 @item
  99   @samp{Format 2} snapshot file begins with a format identifier, as described for
 100 version 1, e.g.:
 101
 102 @smallexample
 103 GNU tar-@value{VERSION}-2
 104 @end smallexample
 105
 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.
 110
 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.
 115
 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.
 121
 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.
 134 @item
 135 @end multitable
 136
 137   Dumpdirs stored in snapshot files contain only records of types
 138 @samp{Y}, @samp{N} and @samp{D}.
 139
 140 @end enumerate
 141
 142 @c End of snapshot.texi