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

   1 @c This is part of the paxutils manual.
   2 @c Copyright (C) 2006, 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   Incremental archives keep information about contents of each
   8 dumped directory in special data blocks called @dfn{dumpdirs}.
   9
  10   Dumpdir is a sequence of entries of the following form:
  11
  12 @smallexample
  13 @var{C} @var{filename} \0
  14 @end smallexample
  15
  16 @noindent
  17 where @var{C} is one of the @dfn{control codes} described below,
  18 @var{filename} is the name of the file @var{C} operates upon, and
  19 @samp{\0} represents a nul character (ASCII 0).  The white space
  20 characters were added for readability, real dumpdirs do not contain
  21 them.
  22
  23   Each dumpdir ends with a single nul character.
  24
  25   The following table describes control codes and their meanings:
  26
  27 @table @samp
  28 @item Y
  29 @var{filename} is contained in the archive.
  30
  31 @item N
  32 @var{filename} was present in the directory at the time the archive
  33 was made, yet it was not dumped to the archive, because it had not
  34 changed since the last backup.
  35
  36 @item D
  37 @var{filename} is a directory.
  38
  39 @item R
  40 This code requests renaming of the @var{filename} to the name
  41 specified with the @samp{T} command, that immediately follows it.
  42
  43 @item T
  44 Specify target file name for @samp{R} command (see below).
  45
  46 @item X
  47 Specify @dfn{temporary directory} name for a rename operation (see below).
  48 @end table
  49
  50   Codes @samp{Y}, @samp{N} and @samp{D} require @var{filename} argument
  51 to be a relative file name to the directory this dumpdir describes,
  52 whereas codes @samp{R}, @samp{T} and @samp{X} require their argument
  53 to be an absolute file name.
  54
  55  The three codes @samp{R}, @samp{T} and @samp{X} specify a
  56 @dfn{renaming operation}.  In the simplest case it is:
  57
  58 @smallexample
  59 R@file{source}\0T@file{dest}\0
  60 @end smallexample
  61
  62 @noindent
  63 which means ``rename file @file{source} to file @file{dest}''.
  64
  65   However, there are cases that require using a @dfn{temporary
  66 directory}.  For example, consider the following scenario:
  67
  68 @enumerate 1
  69 @item
  70 Previous run dumped a directory @file{foo} which contained the
  71 following three directories:
  72
  73 @smallexample
  74 a
  75 b
  76 c
  77 @end smallexample
  78
  79 @item
  80 They were renamed @emph{cyclically}, so that:
  81
  82 @example
  83 @file{a} became @file{b}
  84 @file{b} became @file{c}
  85 @file{c} became @file{a}
  86 @end example
  87
  88 @item
  89 New incremental dump was made.
  90 @end enumerate
  91
  92   This case cannot be handled by three successive renames, since
  93 renaming @file{a} to @file{b} will destroy the existing directory.
  94 To correctly process it, @GNUTAR{} needs a temporary directory, so
  95 it creates the following dumpdir (newlines have been added for
  96 readability):
  97
  98 @smallexample
  99 @group
 100 Xfoo\0
 101 Rfoo/a\0T\0
 102 Rfoo/b\0Tfoo/c\0
 103 Rfoo/c\0Tfoo/a\0
 104 R\0Tfoo/a\0
 105 @end group
 106 @end smallexample
 107
 108   The first command, @samp{Xfoo\0}, instructs the extractor to create a
 109 temporary directory in the directory @file{foo}.  Second command,
 110 @samp{Rfoo/aT\0}, says ``rename file @file{foo/a} to the temporary
 111 directory that has just been created'' (empty file name after a
 112 command means use temporary directory).  Third and fourth commands
 113 work as usual, and, finally, the last command, @samp{R\0Tfoo/a\0}
 114 tells tar to rename the temporary directory to @file{foo/a}.
 115
 116   The exact placement of a dumpdir in the archive depends on the
 117 archive format (@pxref{Formats}):
 118
 119 @itemize
 120 @item PAX archives
 121
 122 In PAX archives, dumpdir is stored in the extended header of the
 123 corresponding directory, in variable @code{GNU.dumpdir}.
 124
 125 @item GNU and old GNU archives
 126
 127 These formats implement special header type @samp{D}, which is similar
 128 to ustar header @samp{5} (directory), except that it precedes a data
 129 block containing the dumpdir.
 130 @end itemize
 131
 132 @c End of dumpdir.texi