Go to the previous, next section.
(This message will disappear, once this node revised.)
-f [hostname:]file
--file=[hostname:]file
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
--rsh-command=command
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]
-M
--multi-volume
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
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
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 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
Go to the previous, next section.