Go to the previous, next section.

Device selection and switching

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

-f [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>'.

Archive file is local even if it contains a colon.

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.

Specify drive and density.

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
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
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 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.