[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

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 section 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 size-suffixes, 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 is(23):

 
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(24).

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 section 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 section 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 section The Five Advanced tar Operations, for a complete list of subcommand options.

TAR_FORMAT

Format of the archive being processed. See section 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 section 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 section 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.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

This document was generated by Sergey Poznyakoff on October, 20 2013 using texi2html 1.78.