Next: Verifying Data as It is Stored, Previous: Using Multiple Tapes, Up: Tapes and Other Archive Media [Contents][Index]
To avoid problems caused by misplaced paper labels on the archive media, you can include a label entry — an archive member which contains the name of the archive — in the archive itself. Use the --label=archive-label (-V archive-label) option28 in conjunction with the --create operation to include a label entry in the archive as it is being created.
Includes an archive-label at the beginning of the archive when the archive is being created, when used in conjunction with the --create operation. Checks to make sure the archive label matches the one specified (when used in conjunction with any other operation).
If you create an archive using both --label=archive-label (-V archive-label) and --multi-volume (-M), each volume of the archive will have an archive label of the form ‘archive-label Volume n’, where n is 1 for the first volume, 2 for the next, and so on. See Using Multiple Tapes, for information on creating multiple volume archives.
The volume label will be displayed by --list along with the file contents. If verbose display is requested, it will also be explicitly marked as in the example below:
$ tar --verbose --list --file=iamanarchive V--------- 0/0 0 1992-03-07 12:01 iamalabel--Volume Header-- -rw-r--r-- ringo/user 40 1990-05-21 13:30 iamafilename
However, --list option will cause listing entire contents of the archive, which may be undesirable (for example, if the archive is stored on a tape). You can request checking only the volume label by specifying --test-label option. This option reads only the first block of an archive, so it can be used with slow storage devices. For example:
$ tar --test-label --file=iamanarchive iamalabel
If --test-label is used with one or more command line
arguments, tar
compares the volume label with each
argument. It exits with code 0 if a match is found, and with code 1
otherwise29. No output is displayed, unless you also used the
--verbose option. For example:
$ tar --test-label --file=iamanarchive 'iamalabel' ⇒ 0 $ tar --test-label --file=iamanarchive 'alabel' ⇒ 1
When used with the --verbose option, tar
prints the actual volume label (if any), and a verbose diagnostics in
case of a mismatch:
$ tar --test-label --verbose --file=iamanarchive 'iamalabel' iamalabel ⇒ 0 $ tar --test-label --verbose --file=iamanarchive 'alabel' iamalabel tar: Archive label mismatch ⇒ 1
If you request any operation, other than --create, along
with using --label option, tar
will first check if
the archive label matches the one specified and will refuse to proceed
if it does not. Use this as a safety precaution to avoid accidentally
overwriting existing archives. For example, if you wish to add files
to archive, presumably labeled with string ‘My volume’,
you will get:
$ tar -rf archive --label 'My volume' . tar: Archive not labeled to match 'My volume'
in case its label does not match. This will work even if archive is not labeled at all.
Similarly, tar
will refuse to list or extract the
archive if its label doesn’t match the archive-label
specified. In those cases, archive-label argument is interpreted
as a globbing-style pattern which must match the actual magnetic
volume label. See Excluding Some Files, for a precise description of how match
is attempted30. If the switch --multi-volume (-M) is being used,
the volume label matcher will also suffix archive-label by
‘ Volume [1-9]*’ if the initial match fails, before giving
up. Since the volume numbering is automatically added in labels at
creation time, it sounded logical to equally help the user taking care
of it when the archive is being read.
You can also use --label to get a common information on all tapes of a series. For having this information different in each series created through a single script used on a regular basis, just manage to get some date string as part of the label. For example:
$ tar -cM -f /dev/tape -V "Daily backup for `date +%Y-%m-%d`" $ tar --create --file=/dev/tape --multi-volume \ --label="Daily backup for `date +%Y-%m-%d`"
Some more notes about volume labels:
tar
initially attempted to write it,
often soon after the operator launches tar
or types the
carriage return telling that the next tape is ready.
Until version 1.10, that option was called --volume, but is not available under that name anymore.
Note that GNU tar
versions up to 1.23 indicated
mismatch with an exit code 2 and printed a spurious diagnostics on
stderr.
Previous versions of tar
used full
regular expression matching, or before that, only exact string
matching, instead of wildcard matchers. We decided for the sake of
simplicity to use a uniform matching device through
tar
.
Next: Verifying Data as It is Stored, Previous: Using Multiple Tapes, Up: Tapes and Other Archive Media [Contents][Index]