file (GNU tar 1.34)

Next: Selecting Archive Members, Up: Choosing [Contents][Index]

### 6.1 Choosing and Naming Archive Files

By default, `tar` uses an archive file name that was compiled when it was built on the system; usually this name refers to some physical tape drive on the machine. However, the person who installed `tar` on the system may not have set the default to a meaningful value as far as most users are concerned. As a result, you will usually want to tell `tar` where to find (or create) the archive. The `--file=archive-name` (`-f archive-name`) option allows you to either specify or name a file to use as the archive instead of the default archive file location.

`--file=archive-name`
`-f archive-name`

  Name the archive to create or operate on. Use in conjunction with any operation.

For example, in this `tar` command,

    $ tar -cvf collection.tar blues folk jazz

`collection.tar` is the name of the archive. It must directly follow the `-f` option, since whatever directly follows `-f` will end up naming the archive. If you neglect to specify an archive name, you may end up overwriting a file in the working directory with the archive you create since `tar` will use this file’s name for the archive name.

An archive can be saved as a file in the file system, sent through a pipe or over a network, or written to an I/O device such as a tape, floppy disk, or CD write drive.

If you do not name the archive, `tar` uses the value of the environment variable `TAPE` as the file name for the archive. If that is not available, `tar` uses a default, compiled-in archive name, usually that for tape unit zero (i.e., `/dev/tu00`).

If you use `-` as an archive-name, `tar` reads the archive from standard input (when listing or extracting files), or writes it to standard output (when creating an archive). If you use `-` as an archive-name when modifying an archive, `tar` reads the original archive from its standard input and writes the entire new archive to its standard output.

The following example is a convenient way of copying directory hierarchy from `sourcedir` to `targetdir`.

    $ (cd sourcedir; tar -cf - .) | (cd targetdir; tar -xpf -)

The `-C` option allows to avoid using subshells:

    $ tar -C sourcedir -cf - . | tar -C targetdir -xpf -

In both examples above, the leftmost `tar` invocation archives the contents of `sourcedir` to the standard output, while the rightmost one reads this archive from its standard input and extracts it. The `-p` option tells it to restore permissions of the extracted files.

To specify an archive file on a device attached to a remote machine, use the following:

    --file=hostname:/dev/file-name

`tar` will set up the remote connection, if possible, and prompt you for a username and password. If you use `--file=@hostname:/dev/file-name`, `tar` will attempt to set up the remote connection using your username as the username on the remote machine.

If the archive file name includes a colon (‘`:`’), then it is assumed to be a file on another machine. If the archive file is ‘`user@host:file`’, then file is used on the host host. The remote host is accessed using the `rsh` program, with a username of user. If the username is omitted (along with the ‘`@`’ sign), then your user name will be used. (This is the normal `rsh` behavior.) It is necessary for the remote machine, in addition to permitting your `rsh` access, to have the `rmt` program installed (this command is included in the GNU `tar` distribution and by default is installed under `prefix/libexec/rmt`, where prefix means your installation prefix). If you need to use a file whose name includes a colon, then the remote tape drive behavior can be inhibited by using the `--force-local` option.

When the archive is being created to `/dev/null`, GNU `tar` tries to minimize input and output operations. The Amanda backup system, when used with GNU `tar`, has an initial sizing pass which uses this feature.

Next: Selecting Archive Members, Up: Choosing [Contents][Index]