1 @c This is part of the paxutils manual.
2 @c Copyright (C) 2006--2022 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.
7 Incremental archives keep information about contents of each
8 dumped directory in special data blocks called @dfn{dumpdirs}.
10 Dumpdir is a sequence of entries of the following form:
13 @var{C} @var{filename} \0
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
23 Each dumpdir ends with a single nul character.
25 The following table describes control codes and their meanings:
29 @var{filename} is contained in the archive.
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.
37 @var{filename} is a directory.
40 This code requests renaming of the @var{filename} to the name
41 specified with the @samp{T} command, that immediately follows it.
44 Specify target file name for @samp{R} command (see below).
47 Specify @dfn{temporary directory} name for a rename operation (see below).
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.
55 The three codes @samp{R}, @samp{T} and @samp{X} specify a
56 @dfn{renaming operation}. In the simplest case it is:
59 R@file{source}\0T@file{dest}\0
63 which means ``rename file @file{source} to file @file{dest}''.
65 However, there are cases that require using a @dfn{temporary
66 directory}. For example, consider the following scenario:
70 Previous run dumped a directory @file{foo} which contained the
71 following three directories:
80 They were renamed @emph{cyclically}, so that:
83 @file{a} became @file{b}
84 @file{b} became @file{c}
85 @file{c} became @file{a}
89 New incremental dump was made.
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
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}.
116 The exact placement of a dumpdir in the archive depends on the
117 archive format (@pxref{Formats}):
122 In PAX archives, dumpdir is stored in the extended header of the
123 corresponding directory, in variable @code{GNU.dumpdir}.
125 @item GNU and old GNU archives
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.
132 @c End of dumpdir.texi