Dogcows Code - chaz/tar/blob - doc/snapshot.texi

   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.
   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 @item
  98   @samp{Format 2} snapshot file begins with a format identifier, as described for
  99 version 1, e.g.:
 100
 101 @smallexample
 102 GNU tar-@value{VERSION}-2
 103 @end smallexample
 104
 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.
 109
 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.
 114
 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.)
 121
 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.
 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 @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:
 147
 148 @smallexample
 149 $ @kbd{tar --show-shapshot-field-ranges}
 150 This tar's snapshot file field ranges are
 151    (field name      => [ min, max ]):
 152
 153     nfs             => [ 0, 1 ],
 154     timestamp_sec   => [ -9223372036854775808, 9223372036854775807 ],
 155     timestamp_nsec  => [ 0, 999999999 ],
 156     dev             => [ 0, 18446744073709551615 ],
 157     ino             => [ 0, 18446744073709551615 ],
 158 @end smallexample
 159
 160 (This example is from a GNU/Linux x86_64 system.)
 161
 162 @end enumerate
 163
 164 @c End of snapshot.texi