tar: Dumpdir

1 
1 Dumpdir
1 =======
1 
1 Incremental archives keep information about contents of each dumped
1 directory in special data blocks called "dumpdirs".
1 
1    Dumpdir is a sequence of entries of the following form:
1 
1      C FILENAME \0
1 
1 where C is one of the "control codes" described below, FILENAME is the
1 name of the file C operates upon, and '\0' represents a nul character
1 (ASCII 0).  The white space characters were added for readability, real
1 dumpdirs do not contain them.
1 
1    Each dumpdir ends with a single nul character.
1 
1    The following table describes control codes and their meanings:
1 
1 'Y'
1      FILENAME is contained in the archive.
1 
1 'N'
1      FILENAME was present in the directory at the time the archive was
1      made, yet it was not dumped to the archive, because it had not
1      changed since the last backup.
1 
1 'D'
1      FILENAME is a directory.
1 
1 'R'
1      This code requests renaming of the FILENAME to the name specified
1      with the 'T' command, that immediately follows it.
1 
1 'T'
1      Specify target file name for 'R' command (see below).
1 
1 'X'
1      Specify "temporary directory" name for a rename operation (see
1      below).
1 
1    Codes 'Y', 'N' and 'D' require FILENAME argument to be a relative
1 file name to the directory this dumpdir describes, whereas codes 'R',
1 'T' and 'X' require their argument to be an absolute file name.
1 
1    The three codes 'R', 'T' and 'X' specify a "renaming operation".  In
1 the simplest case it is:
1 
1      Rsource\0Tdest\0
1 
1 which means "rename file 'source' to file 'dest'".
1 
1    However, there are cases that require using a "temporary directory".
1 For example, consider the following scenario:
1 
1   1. Previous run dumped a directory 'foo' which contained the following
1      three directories:
1 
1           a
1           b
1           c
1 
1   2. They were renamed _cyclically_, so that:
1 
1           a became b
1           b became c
1           c became a
1 
1   3. New incremental dump was made.
1 
1    This case cannot be handled by three successive renames, since
1 renaming 'a' to 'b' will destroy the existing directory.  To correctly
1 process it, GNU 'tar' needs a temporary directory, so it creates the
1 following dumpdir (newlines have been added for readability):
1 
1      Xfoo\0
1      Rfoo/a\0T\0
1      Rfoo/b\0Tfoo/c\0
1      Rfoo/c\0Tfoo/a\0
1      R\0Tfoo/a\0
1 
1    The first command, 'Xfoo\0', instructs the extractor to create a
1 temporary directory in the directory 'foo'.  Second command,
1 'Rfoo/aT\0', says "rename file 'foo/a' to the temporary directory that
1 has just been created" (empty file name after a command means use
1 temporary directory).  Third and fourth commands work as usual, and,
1 finally, the last command, 'R\0Tfoo/a\0' tells tar to rename the
1 temporary directory to 'foo/a'.
1 
1    The exact placement of a dumpdir in the archive depends on the
1 archive format (⇒Formats):
1 
1    * PAX archives
1 
1      In PAX archives, dumpdir is stored in the extended header of the
1      corresponding directory, in variable 'GNU.dumpdir'.
1 
1    * GNU and old GNU archives
1 
1      These formats implement special header type 'D', which is similar
1      to ustar header '5' (directory), except that it precedes a data
1      block containing the dumpdir.
1