Dumpdir (GNU tar 1.34)

Previous: Snapshot Files, Up: Tar Internals [Contents][Index]

### 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:

    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 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 Formats):

- 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.

Previous: Snapshot Files, Up: Tar Internals [Contents][Index]