Previous: Snapshot Files, Up: Tar Internals

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 following ‘T’ command.
‘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: 

     Rsource\0Tdest\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 existing directory. To handle such case a temporary directory is required. GNU tar will create 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 Formats):