File: tar.info,  Node: Multi-Volume Archives,  Next: Tape Files,  Up: Using Multiple Tapes

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 (*note create::).  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
     (*note Table 9.1: 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(1):

     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:
   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'(2).

`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 *note
label::, 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=SCRIPT-NAME'
`--new-volume-script=SCRIPT-NAME'
`-F SCRIPT-NAME'
     Specify the full name of the volume script to use.  The script can
     be used to eject cassettes, or to broadcast messages such as
     `Someone please come change my tape' when performing unattended
     backups.

   The SCRIPT-NAME is executed without any command line arguments.  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 (*note Blocking::).

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

`TAR_SUBCOMMAND'
     A short option describing the operation `tar' is executing.  *Note
     Operations::, for a complete list of subcommand options.

`TAR_FORMAT'
     Format of the archive being processed. *Note Formats::, for a
     complete list of archive format names.

`TAR_FD'
     File descriptor which can be used to communicate the new volume
     name to `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 cMff /dev/tape0 /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/sh
     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
     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.
*Note extracting archives::, 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'
(*note label::) 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 *note Split Recovery::.

   ---------- Footnotes ----------

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

   (2) *Note --restrict::, for more information about this option.