Multi-Volume Archives (GNU tar 1.35)

#### 9.6.1 Archives Longer than One Tape or Disk

To create an archive that is larger than will fit on a single unit of the media, use the `--multi-volume` (`-M`) option in conjunction with the `--create` option (see How to Create Archives). A multi-volume archive can be manipulated like any other archive (provided the `--multi-volume` option is specified), but is stored on more than one tape or file.

When you specify `--multi-volume`, `tar` does not report an error when it comes to the end of an archive volume (when reading), or the end of the media (when writing). Instead, it prompts you to load a new storage volume. If the archive is on a magnetic tape, you should change tapes when you see the prompt; if the archive is on a floppy disk, you should change disks; etc.

`--multi-volume`
`-M`

  Creates a multi-volume archive, when used in conjunction with `--create` (`-c`). To perform any other operation on a multi-volume archive, specify `--multi-volume` in conjunction with that operation. For example:

      $ tar --create --multi-volume --file=/dev/tape files

The method `tar` uses to detect end of tape is not perfect, and fails on some operating systems or on some devices. If `tar` cannot detect the end of the tape itself, you can use `--tape-length` option to inform it about the capacity of the tape:

`--tape-length=size[suf]`
`-L size[suf]`

  Set maximum length of a volume. The suf, if given, specifies units in which size is expressed, e.g. ‘`2M`’ mean 2 megabytes (see Table 9.1, for a list of allowed size suffixes). Without suf, units of 1024 bytes (kilobyte) are assumed.

  This option selects `--multi-volume` automatically. For example:

      $ tar --create --tape-length=41943040 --file=/dev/tape files

  or, which is equivalent:

      $ tar --create --tape-length=4G --file=/dev/tape files

When GNU `tar` comes to the end of a storage media, it asks you to change the volume. The built-in prompt for POSIX locale is27:

    Prepare volume #n for 'archive' and hit return:

where n is the ordinal number of the volume to be created and archive is archive file or device name.

When prompting for a new tape, `tar` accepts any of the following responses:

`?`

  Request `tar` to explain possible responses.

`q`

  Request `tar` to exit immediately.

`n file-name`

  Request `tar` to write the next volume on the file file-name.

`!`

  Request `tar` to run a subshell. This option can be disabled by giving `--restrict` command line option to `tar`28.

`y`

  Request `tar` to begin writing the next volume.

(You should only type ‘`y`’ after you have changed the tape; otherwise `tar` will write over the volume it just finished.)

The volume number used by `tar` in its tape-changing prompt can be changed; if you give the `--volno-file=file-of-number` option, then file-of-number should be an non-existing file to be created, or else, a file already containing a decimal number. That number will be used as the volume number of the first volume written. When `tar` is finished, it will rewrite the file with the now-current volume number. (This does not change the volume number written on a tape label, as per Including a Label in the Archive, it only affects the number used in the prompt.)

If you want more elaborate behavior than this, you can write a special new volume script, that will be responsible for changing the volume, and instruct `tar` to use it instead of its normal prompting procedure:

`--info-script=command`
`--new-volume-script=command`
`-F command`

  Specify the command to invoke when switching volumes. The command can be used to eject cassettes, or to broadcast messages such as ‘`Someone please come change my tape`’ when performing unattended backups.

The command can contain additional options, if such are needed. See Running External Commands, for a detailed discussion of the way GNU `tar` runs external commands. It inherits `tar`’s shell environment. Additional data is passed to it via the following environment variables:

`TAR_VERSION`

  GNU `tar` version number.

`TAR_ARCHIVE`

  The name of the archive `tar` is processing.

`TAR_BLOCKING_FACTOR`

  Current blocking factor (see Blocking).

`TAR_VOLUME`

  Ordinal number of the volume `tar` is about to start.

`TAR_SUBCOMMAND`

  A short option describing the operation `tar` is executing. See The Five Advanced `tar` Operations, for a complete list of subcommand options.

`TAR_FORMAT`

  Format of the archive being processed. See Controlling the Archive Format, for a complete list of archive format names.

`TAR_FD`

  File descriptor which can be used to communicate the new volume name to `tar`.

These variables can be used in the command itself, provided that they are properly quoted to prevent them from being expanded by the shell that invokes `tar`.

The volume script can instruct `tar` to use new archive name, by writing in to file descriptor `$TAR_FD` (see below for an example).

If the info script fails, `tar` exits; otherwise, it begins writing the next volume.

If you want `tar` to cycle through a series of files or tape drives, there are three approaches to choose from. First of all, you can give `tar` multiple `--file` options. In this case the specified files will be used, in sequence, as the successive volumes of the archive. Only when the first one in the sequence needs to be used again will `tar` prompt for a tape change (or run the info script). For example, suppose someone has two tape drives on a system named `/dev/tape0` and `/dev/tape1`. For having GNU `tar` to switch to the second drive when it needs to write the second tape, and then back to the first tape, etc., just do either of:

    $ tar --create --multi-volume --file=/dev/tape0 --file=/dev/tape1 files
    $ tar -cM -f /dev/tape0 -f /dev/tape1 files

The second method is to use the ‘`n`’ response to the tape-change prompt.

Finally, the most flexible approach is to use a volume script, that writes new archive name to the file descriptor `$TAR_FD`. For example, the following volume script will create a series of archive files, named `archive-vol`, where archive is the name of the archive being created (as given by `--file` option) and vol is the ordinal number of the archive being created:

    #! /bin/bash
    # For this script it's advisable to use a shell, such as Bash,
    # that supports a TAR_FD value greater than 9.

    echo Preparing volume $TAR_VOLUME of $TAR_ARCHIVE.

    name=`expr $TAR_ARCHIVE : '\(.*\)-.*'`
    case $TAR_SUBCOMMAND in
    -c)       ;;
    -d|-x|-t) test -r ${name:-$TAR_ARCHIVE}-$TAR_VOLUME || exit 1
              ;;
    *)        exit 1
    esac

    echo ${name:-$TAR_ARCHIVE}-$TAR_VOLUME >&$TAR_FD

The same script can be used while listing, comparing or extracting from the created archive. For example:

    # Create a multi-volume archive:
    $ tar -c -L1024 -f archive.tar -F new-volume .
    # Extract from the created archive:
    $ tar -x -f archive.tar -F new-volume .

Notice, that the first command had to use `-L` option, since otherwise GNU `tar` will end up writing everything to file `archive.tar`.

You can read each individual volume of a multi-volume archive as if it were an archive by itself. For example, to list the contents of one volume, use `--list`, without `--multi-volume` specified. To extract an archive member from one volume (assuming it is described that volume), use `--extract`, again without `--multi-volume`.

If an archive member is split across volumes (i.e., its entry begins on one volume of the media and ends on another), you need to specify `--multi-volume` to extract it successfully. In this case, you should load the volume where the archive member starts, and use ‘`tar --extract --multi-volume`’—`tar` will prompt for later volumes as it needs them. See Extracting an Entire Archive, for more information about extracting archives.

Multi-volume archives can be modified like any other archive. To add files to a multi-volume archive, you need to only mount the last volume of the archive media (and new volumes, if needed). For all other operations, you need to use the entire archive.

If a multi-volume archive was labeled using `--label=archive-label` (see Including a Label in the Archive) when it was created, `tar` will not automatically label volumes which are added later. To label subsequent volumes, specify `--label=archive-label` again in conjunction with the `--append`, `--update` or `--concatenate` operation.

Notice that multi-volume support is a GNU extension and the archives created in this mode should be read only using GNU `tar`. If you absolutely have to process such archives using a third-party `tar` implementation, read Extracting Members Split Between Volumes.

#### Footnotes

##### (27)

If you run GNU `tar` under a different locale, the translation to the locale’s language will be used.

##### (28)

See --restrict, for more information about this option.