(tar)Device

Blocking

Media

Media

Device selection and switching
==============================

     *(This message will disappear, once this node revised.)*

`-f [HOSTNAME:]FILE'
`--file=[HOSTNAME:]FILE'
     Use archive file or device FILE on HOSTNAME.

     This option is used to specify the file name of the archive `tar'
     works on.

     If the file name is `-', `tar' reads the archive from standard
     input (when listing or extracting), or writes it to standard output
     (when creating).  If the `-' file name is given when updating an
     archive, `tar' will read the original archive from its standard
     input, and will write the entire new archive to its standard
     output.

     If the file name contains a `:', it is interpreted as
     `hostname:filename'.  If the HOSTNAME contains an "at" sign (`@'),
     it is treated as `user@hostname:filename'.  In either case, `tar'
     will invoke the command `rsh' (or `remsh') to start up an
     `/etc/rmt' on the remote machine.  If you give an alternate login
     name, it will be given to the `rsh'.  Naturally, the remote
     machine must have an executable `/etc/rmt'.  This program is free
     software from the University of California, and a copy of the
     source code can be found with the sources for `tar'; it's compiled
     and installed by default.

     If this option is not given, but the environment variable `TAPE' is
     set, its value is used; otherwise, old versions of `tar' used a
     default archive name (which was picked when `tar' was compiled).
     The default is normally set up to be the "first" tape drive or
     other transportable I/O medium on the system.

     Starting with version 1.11.5, GNU `tar' uses standard input and
     standard output as the default device, and I will not try anymore
     supporting automatic device detection at installation time.  This
     was failing really in too many cases, it was hopeless.  This is now
     completely left to the installer to override standard input and
     standard output for default device, if this seems preferrable to
     him/her.  Further, I think *most* actual usages of `tar' are done
     with pipes or disks, not really tapes, cartridges or diskettes.

     Some users think that using standard input and output is running
     after trouble.  This could lead to a nasty surprise on your screen
     if you forget to specify an output file name--especially if you
     are going through a network or terminal server capable of
     buffering large amounts of output.  We had so many bug reports in
     that area of configuring default tapes automatically, and so many
     contradicting requests, that we finally consider the problem to be
     portably intractable.  We could of course use something like
     `/dev/tape' as a default, but this is *also* running after various
     kind of trouble, going from hung processes to accidental
     destruction of real tapes.  After having seen all this mess, using
     standard input and output as a default really sounds like the only
     clean choice left, and a very useful one too.

     GNU `tar' reads and writes archive in blocks, I suspect this is the
     main reason why block devices are preferred over character devices.
     Most probably, block devices are more efficient too.  The installer
     could also check for `DEFTAPE' in `<sys/mtio.h>'.

`--force-local'
     Archive file is local even if it contains a colon.

`--rsh-command=COMMAND'
     Use remote COMMAND instead of `rsh'.  This option exists so that
     people who use something other than the standard `rsh' (e.g., a
     Kerberized `rsh') can access a remote device.

     When this command is not used, the shell command found when the
     `tar' program was installed is used instead.  This is the first
     found of `/usr/ucb/rsh', `/usr/bin/remsh', `/usr/bin/rsh',
     `/usr/bsd/rsh' or `/usr/bin/nsh'.  The installer may have
     overriden this by defining the environment variable `RSH' *at
     installation time*.

`-[0-7][lmh]'
     Specify drive and density.

`-M'
`--multi-volume'
     Create/list/extract multi-volume archive.

     This option causes `tar' to write a "multi-volume" archive--one
     that may be larger than will fit on the medium used to hold it.
     FIXME: xref Multi
     .

`-L NUM'
`--tape-length=NUM'
     Change tape after writing NUM x 1024 bytes.

     This option might be useful when your tape drivers do not properly
     detect end of physical tapes.  By being slightly conservative on
     the maximum tape length, you might avoid the problem entirely.

`-F FILE'
`--info-script=FILE'
`--new-volume-script=FILE'
     Execute `file' at end of each tape.  This implies `--multi-volume'
     (`-M').

   The Remote Tape Server

   In order to access the tape drive on a remote machine, `tar' uses
the remote tape server written at the University of California at
Berkeley.  The remote tape server must be installed as `/etc/rmt' on
any machine whose tape drive you want to use.  `tar' calls `/etc/rmt'
by running an `rsh' or `remsh' to the remote machine, optionally using
a different login name if one is supplied.

   A copy of the source for the remote tape server is provided.  It is
Copyright (C) 1983 by the Regents of the University of California, but
can be freely distributed.  Instructions for compiling and installing
it are included in the `Makefile'.

   Unless you use the {No Value For "absolue-names"} option, GNU `tar'
will not allow you to create an archive that contains absolute file
names (a file name beginning with `/'.) If you try, `tar' will
automatically remove the leading `/' from the file names it stores in
the archive.  It will also type a warning message telling you what it
is doing.

   When reading an archive that was created with a different `tar'
program, GNU `tar' automatically extracts entries in the archive which
have absolute file names as if the file names were not absolute.  This
is an important feature.  A visitor here once gave a `tar' tape to an
operator to restore; the operator used Sun `tar' instead of GNU `tar',
and the result was that it replaced large portions of our `/bin' and
friends with versions from the tape; needless to say, we were unhappy
about having to recover the file system from backup tapes.

   For example, if the archive contained a file `/usr/bin/computoy',
GNU `tar' would extract the file to `usr/bin/computoy', relative to the
current directory.  If you want to extract the files in an archive to
the same absolute names that they had when the archive was created, you
should do a `cd /' before extracting the files from the archive, or you
should either use the `--absolute-names' (`-P') option, or use the
command `tar -C / ...'.

   Some versions of Unix (Ultrix 3.1 is know to have this problem), can
claim that a short write near the end of a tape succeeded, when it
actually failed.  This will result in the -M option not working
correctly.  The best workaround at the moment is to use a significantly
larger blocksize than the default 20.

   In order to update an archive, `tar' must be able to backspace the
archive in order to reread or rewrite a block that was just read (or
written).  This is currently possible only on two kinds of files: normal
disk files (or any other file that can be backspaced with `lseek'), and
industry-standard 9-track magnetic tape (or any other kind of tape that
can be backspaced with the `MTIOCTOP' `ioctl'.

   This means that the `--append' (`-r'), `--update' (`-u'),
`--concatenate' (`-A'), and `--delete' commands will not work on any
other kind of file.  Some media simply cannot be backspaced, which
means these commands and options will never be able to work on them.
These non-backspacing media include pipes and cartridge tape drives.

   Some other media can be backspaced, and `tar' will work on them once
`tar' is modified to do so.

   Archives created with the `--multi-volume' (`-M'),
`--label=ARCHIVE-LABEL' (`-V ARCHIVE-LABEL'), and `--incremental'
(`-G') options may not be readable by other version of `tar'.  In
particular, restoring a file that was split over a volume boundary will
require some careful work with `dd', if it can be done at all.  Other
versions of `tar' may also create an empty file whose name is that of
the volume header.  Some versions of `tar' may create normal files
instead of directories archived with the `--incremental' (`-G') option.

   Some Common Problems and their Solutions:

errors from system:
permission denied
no such file or directory
not owner

errors from `tar':
directory checksum error
header format error

errors from media/system:
i/o error
device busy