Dumpdir

Incremental archives keep information about contents of each dumped directory in special data blocks called dumpdirs.

Dumpdir is a sequence of entries of the following form:

C filename \0

where C is one of the control codes described below, filename is the name of the file C operates upon, and ‘\0’ represents a nul character (ASCII 0). The white space characters were added for readability, real dumpdirs do not contain them.

Each dumpdir ends with a single nul character.

The following table describes control codes and their meanings:

‘Y’

filename is contained in the archive.

‘N’

filename was present in the directory at the time the archive was made, yet it was not dumped to the archive, because it had not changed since the last backup.

‘D’

filename is a directory.

‘R’

This code requests renaming of the filename to the name specified with the ‘T’ command, that immediately follows it.

‘T’

Specify target file name for ‘R’ command (see below).

‘X’

Specify temporary directory name for a rename operation (see below).

Codes ‘Y’, ‘N’ and ‘D’ require filename argument to be a relative file name to the directory this dumpdir describes, whereas codes ‘R’, ‘T’ and ‘X’ require their argument to be an absolute file name.

The three codes ‘R’, ‘T’ and ‘X’ specify a renaming operation. In the simplest case it is:

R‘source’\0T‘dest’\0

which means “rename file ‘source’ to file ‘dest’”.

However, there are cases that require using a temporary directory. For example, consider the following scenario:

1. Previous run dumped a directory ‘foo’ which contained the following three directories:

   a
   b
   c
   

2. They were renamed cyclically, so that:

   ‘a’ became ‘b’
   ‘b’ became ‘c’
   ‘c’ became ‘a’
   

3. New incremental dump was made.

This case cannot be handled by three successive renames, since renaming ‘a’ to ‘b’ will destroy the existing directory. To correctly process it, GNU tar needs a temporary directory, so it creates the following dumpdir (newlines have been added for readability):

Xfoo\0
Rfoo/a\0T\0
Rfoo/b\0Tfoo/c\0
Rfoo/c\0Tfoo/a\0
R\0Tfoo/a\0

The first command, ‘Xfoo\0’, instructs the extractor to create a temporary directory in the directory ‘foo’. Second command, ‘Rfoo/aT\0’, says “rename file ‘foo/a’ to the temporary directory that has just been created” (empty file name after a command means use temporary directory). Third and fourth commands work as usual, and, finally, the last command, ‘R\0Tfoo/a\0’ tells tar to rename the temporary directory to ‘foo/a’.

The exact placement of a dumpdir in the archive depends on the archive format (see section Controlling the Archive Format):

• PAX archives

  In PAX archives, dumpdir is stored in the extended header of the corresponding directory, in variable GNU.dumpdir.

• GNU and old GNU archives

  These formats implement special header type ‘D’, which is similar to ustar header ‘5’ (directory), except that it precedes a data block containing the dumpdir.

This document was generated on November 1, 2013 using texi2html 5.0.