3. Options That Change How tar Works

Options may be specified as individual arguments starting with `-'. In this case, if the option wants an argument (as does, for example, `-f') then the argument should come after the option, separated from it by a space. All options are optional. Some options make sense with any command, while others are meaningful only with particular commands.

3.1 Options That Are Always Meaningful

`-b number'

`+block-size number'

This option is used to specify a blocking factor for the archive. When reading or writing the archive, tar, will do reads and writes of the archive in blocks of number*512 bytes. The default blocking factor is set when tar is compiled, and is typically 20. Blocking factors larger than 20 cannot be read by very old versions of tar, or by some newer versions of tar running on old machines with small address spaces. With a magnetic tape, larger blocks give faster throughput and fit more data on a tape (because there are fewer inter-record gaps). If the archive is in a disk file or a pipe, you may want to specify a smaller blocking factor, since a large one will result in a large number of null bytes at the end of the archive. When writing cartridge or other streaming tapes, a much larger blocking factor (say 126 or more) will greatly increase performance. However, you must specify the same blocking factor when reading or updating the archive. With GNU tar the blocking factor is limited only by the maximum block size of the device containing the archive, or by the amount of available virtual memory.

`-f filename'

`+file filename'

This option is used to specify the file name of the archive tar works on. If this option is not given, but the environment variable TAPE is set, its value is used; otherwise, a default archive name (which was picked when tar was compiled) is used. The default is normally set up to be the "first" tape drive or other transportable I/O medium on the system. If the filename is `-', tar reads the archive from standard input (when listing or extracting), or writes it to standard output (when creating). If the `-' filename 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 filename contains `:/dev/', 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 a copy of `/etc/rmt'. /etc/rmt is free software from the University of California, and a copy of the source code can be found with the sources for tar. /etc/rmt will have to be modified to run on non-BSD4.3 systems.

`-C dir'

`+directory dir'

This option causes tar to change into the directory dir before continuing. This option is usually interspersed with the files tar is to work on. For example,

tar -c iggy ziggy -C baz melvin

will place the files `iggy' and `ziggy' from the current directory on the tape, followed by the file `melvin' from the directory `baz'. This option is especially useful when you have several widely separated files that you want to store in the same directory in the archive. Note that the file `melvin' is recorded in the archive under the precise name `melvin', not `baz/melvin'. Thus, the archive will contain three files that all appear to have come from the same directory; if the archive is extracted with plain `tar -x', all three files will be created in the current directory. Contrast this with the command

tar -c iggy ziggy bar/melvin

which records the third file in the archive under the name `bar/melvin' so that, if plain `tar -x' is used, the third file will be created in a subdirectory named `bar'.

`-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. When this option is used, tar will not abort when it cannot read or write any more data. Instead, it will ask you to prepare a new volume. If the archive is on a magnetic tape, you should change tapes now; if the archive is on a floppy disk, you should change disks, etc. Each volume of a multi-volume archive is an independent tar archive, complete in itself. For example, you can list or extract any volume alone (just don't specify `-M'). However, if one file in the archive is split across volumes, the only way to extract it successfully is with a multi-volume extract command (`-xM') starting on or before the volume where the file begins.

`-N date'

`+after-date date'

This option causes tar to only work on files whose modification or inode-changed times are newer than the date given. The main use is for creating an archive; then only new files are written. If extracting, only newer files are extracted. Remember that the entire date argument should be quoted if it contains any spaces. The date is parsed using getdate.

`-R'

`+record-number'

If `-R' is used, tar prints, along with every message it would normally produce, the record number within the archive where the message occurred. This option is especially useful when reading damaged archives, since it helps pinpoint the damaged sections. This can also be useful when making a log of a file-system backup tape, since the results allow you to find the file you want to retrieve on several backup tapes and choose the tape where the file appears earliest (closest to the front of the tape).

`-T filename'

`+files-from filename'

Instead of taking the list of files to work on from the command line, the list of files to work on is read from the file filename. If filename is given as `-', the list is read from standard input. Note that using both `-T -' and `-f -' will not work unless you are using the `-c' command.

`-v'

`+verbose'

This option causes tar to be verbose about the actions it is taking. Normally, the `-t' command to list an archive prints just the file names (one per line) and the other commands are silent. `-tv' prints a full line of information about each file, like the output of `ls -l'. `-v' with any other command (aside from `-t') prints just the name of each file operated on. The output from `-v' appears on the standard output except when creating or updating an archive to the standard output, in which case the output from `-v' is sent to the standard error.

`+version'

This option causes tar to print out its version number to the standard error. It has no equivalent short option name.

`-w'

`+interactive'

This option causes tar to print a message for each action it intends to take, and ask for confirmation on the terminal. To confirm, you must type a line of input. If your input line begins with `y', the action is performed, otherwise it is skipped. The actions which require confirmation include adding a file to the archive, extracting a file from the archive, deleting a file from the archive, and deleting a file from disk. If tar is reading the archive from the standard input, tar will open the file `/dev/tty' to ask for confirmation on.

`-X file'

`+exclude file'

This option causes tar to read a list of filename regular expressions, one per line, from the file file; tar will ignore files with those names. Thus if tar is called as `tar -c -X foo .' and the file `foo' contains `*.o' none of the files whose names end in `.o' in the current directory (or any subdirectory of the current directory) will be added to the archive. Multiple -X options may be given.

`-z'

`-Z'

`+compress'

`+uncompress'

The archive should be compressed as it is written, or decompressed as it is read, using the compress program. This option works on physical devices (tape drives, etc.) and remote files as well as on normal files; data to or from such devices or remote files is reblocked by another copy of the tar program to enforce the specified (or default) block size. The default compression parameters are used; if you need to override them, avoid the `-z' option and run compress explicitly. If the `-z' option is given twice, or the `+compress-block' option is used, tar will pad the archive out to the next block boundry (see section 3.1 Options That Are Always Meaningful). This may be useful with some devices that require that all write operations be a multiple of a certain size. Note that the `-z' option will not work with the `-M' option, or with the `-u', `-r', `-A', or `-D' commands.

3.2 Options for Creating Or Updating an Archive

These options are used to control which files tar puts in an archive, or to control the format the archive is written in (see section 8. The Format of a tar Archive).

Except as noted below, these options are useful with the `-c', `-r', `-u', `-A', and `-D' commands. Also note that the `-B' option, (see section 3.3 Options for Listing Or Extracting Files), is also useful with the `-r', `-u', `-A', and `-D' commands.

`-G'

`+incremental'

This option should only be used when creating an incremental backup of a filesystem. When the `-G' option is used, tar writes, at the beginning of the archive, an entry for each of the directories that will be operated on. The entry for a directory includes a list of all the files in the directory at the time the dump was done, and a flag for each file indicating whether the file is going to be put in the archive. This information is used when doing a complete incremental restore. Note that this option causes tar to create a non-standard archive that may not be readable by non-GNU versions of the tar program.

`-h'

`+dereference'

If `-h' is used, when tar encounters a symbolic link, it will archive the linked-to file, instead of simply recording the presence of a symbolic link. If the linked-to file is archived again, an entire second copy of it will be archived, instead of a link. This could be considered a bug.

`-l'

`+one-file-system'

This option causes tar to not cross filesystem boundaries when archiving parts of a directory tree. This option only affects files that are archived because they are in a directory that is archived; files named on the command line are archived regardless, and they can be from various file systems. This option is useful for making full or incremental archival backups of a file system, as with the Unix dump command. Files which are skipped due to this option are mentioned on the standard error.

`-o'

`+old-archive'

`+old'

`+portability'

This option causes tar to write an old format archive, which does not include information about directories, pipes, fifos, contiguous files, or device files, and specifies file ownership by numeric user- and group-ids rather than by user and group names. In most cases, a new format archive can be read by an old tar program without serious trouble, so this option should seldom be needed. When updating an archive, do not use `-o' unless the archive was created with the `-o' option.

`-S'

`+sparse'

This option causes all files to be put in the archive to be tested for sparseness, and handled specially if they are. The `-S' option is useful when many dbm files, for example, are being backed up, and running out of space on the tape is an issue. Using this option dramatically decreases the amount of space needed to store such a file. In later versions, this option may be removed, and the testing and treatment of sparse files may be done automatically with any special GNU options. For now, it is an option needing to be specified on the command line with the creation or updating of an archive.

`-V name'

`+volume name'

This option causes tar to write out a volume header at the beginning of the archive. If `-M' is used, each volume of the archive will have a volume header of `name Volume N', where N is 1 for the first volume, 2 for the next, and so on.

`-W'

`+verify'

This option causes tar to verify the archive after writing it. Each volume is checked after it is written, and any discrepancies are recorded on the standard error output. Verification requires that the archive be on a back-space-able medium. This means pipes, some cartridge tape drives, and some other devices cannot be verified.

3.3 Options for Listing Or Extracting Files

The options in this section are meaningful with the `-x' command. Unless otherwise stated, they are also meaningful with the `-t' command.

`-B'

`+read-full-blocks'

If `-B' is used, tar will not panic if an attempt to read a block from the archive does not return a full block. Instead, tar will keep reading until it has obtained a full block. This option is turned on by default when tar is reading an archive from standard input, or from a remote machine. This is because on BSD Unix systems, a read of a pipe will return however much happens to be in the pipe, even if it is less than tar requested. If this option was not used, tar would fail as soon as it read an incomplete block from the pipe. This option is also useful with the commands for updating an archive.

`-G'

`+incremental'

The `-G' option means the archive is an incremental backup. Its meaning depends on the command that it modifies. If the `-G' option is used with `-t', tar will list, for each directory in the archive, the list of files in that directory at the time the archive was created. This information is put out in a format that is not easy for humans to read, but which is unambiguous for a program: each filename is preceded by either a `Y' if the file is present in the archive, an `N' if the file is not included in the archive, or a `D' if the file is a directory (and is included in the archive). Each filename is terminated by a null character. The last file is followed by an additional null and a newline to indicate the end of the data. If the `-G' option is used with `-x', then when the entry for a directory is found, all files that currently exist in that directory but are not listed in the archive are deleted from the directory. This behavior is convenient when you are restoring a damaged file system from a succession of incremental backups: it restores the entire state of the file system to that which obtained when the backup was made. If you don't use `-G', the file system will probably fill up with files that shouldn't exist any more.

`-i'

`+ignore-zeros'

The `-i' option causes tar to ignore blocks of zeros in the archive. Normally a block of zeros indicates the end of the archive, but when reading a damaged archive, or one which was created by cat-ing several archives together, this option allows tar to read the entire archive. This option is not on by default because many versions of tar write garbage after the zeroed blocks. Note that this option causes tar to read to the end of the archive file, which may sometimes avoid problems when multiple files are stored on a single physical tape.

`-k'

`+keep-old-files'

The `-k' option prevents tar from over-writing existing files with files with the same name from the archive. The `-k' option is meaningless with `-t'.

`-K filename'

`+starting-file filename'

The `-K' option causes tar to begin extracting or listing the archive with the file filename, and to consider only the files starting at that point in the archive. This is useful if a previous attempt to extract files failed when it reached filename due to lack of free space. (This assumes, of course, that there is now free space, or that you are now extracting into a different file system.)

`-m'

`+modification-time'

When this option is used, tar leaves the modification times of the files it extracts as the time when the files were extracted, instead of setting it to the time recorded in the archive. This option is meaningless with `-t'.

`-O'

`+to-stdout'

When this option is used, instead of creating the files specified, tar writes the contents of the files extracted to its standard output. This may be useful if you are only extracting the files in order to send them through a pipe. This option is meaningless with `-t'.

`-p'

`+same-permissions'

`+preserve-permissions'

This option causes tar to set the modes (access permissions) of extracted files exactly as recorded in the archive. If this option is not used, the current umask setting limits the permissions on extracted files. This option is meaningless with `-t'.

`-P'

`+absolute-paths'

This option should be used when the absolute pathname of a file should be preserved in the archive. tar normally strips the leading `/' from the name of the file, thus making /usr/foo/bar/baz into usr/foo/bar/baz. Using the `-P' option keeps the pathname intact, and is useful in that it is not necessary to change to the root directory when extracting files.

`-s'

`+same-order'

`+preserve-order'

This option tells tar that the list of filenames to be listed or extracted is sorted in the same order as the files in the archive. This allows a large list of names to be used, even on a small machine that would not otherwise be able to hold all the names in memory at the same time. Such a sorted list can easily be created by running `tar -t' on the archive and editing its output. This option is probably never needed on modern computer systems.

`+preserve'

The `+preserve' option has no equivalent short option name. It is equivalent to `-p' plus `-s'.

3.4 Old Syntax for Options

For compatibility with Unix tar, the first argument can contain option letters in addition to the command letter; for example, `tar cv' specifies the option `-v' in addition to the command `-c'. The first argument to GNU tar is always treated as command and option letters even if it doesn't start with `-'.

Some options need their own arguments; for example, `-f' is followed by the name of the archive file. When the option is given separately, its argument follows it, as is usual for Unix programs. For example:

tar -c -v -b 20 -f /dev/rmt0

When options that need arguments are given together with the command, all the associated arguments follow, in the same order as the options. Thus, the example above could also be written in the old style as follows:

tar cvbf 20 /dev/rmt0

Here `20' is the argument of `-b' and `/dev/rmt0' is the argument of `-f'.

The long-named options can be used instead of the single-letter flags. They are meant to be obvious and easy to remember, possibly more so than their corresponding single-letter options. The above example using long-named options would look like this:

tar +create +verbose +block-size +file 20 /dev/rmt0

Go to the first, previous, next, last section, table of contents.