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

Being Even More Careful

GNU tar documentation

Being careful, the first thing is really checking that you are using GNU tar, indeed. The `--version' option will generate a message giving confirmation that you are using GNU tar, with the precise version of GNU tar you are using. tar identifies itself and prints the version number to the standard output, then immediately exits successfully, without doing anything else, ignoring all other options. For example, `tar --version' might return:

GNU tar version 1.11.9

Another thing you might want to do is checking the spelling or meaning of some particular tar option, without resorting to this manual, for once you have carefully read it. GNU tar has a short help feature, triggerable through the `--help' option. By using this option, tar will print a usage message listing all available options on standard output, then exit successfully, without doing anything else and ignoring all other options. Even if this is only a brief summary, it may be several screens long. So, if you are not using some kind of scrollable window, you might prefer to use something like:

tar --help | less

presuming, here, that you like using less for a pager. Other popular pagers are more and pg.

The perceptive reader would have noticed some contradiction in the previous paragraphs. It is written that both `--version' and `--help' print something, and have all other options ignored. In fact, they cannot ignore each other, and one of them has to win. We do not specify which is stronger, here; experiment if you really wonder!

The short help output is quite succint, and you might have to get back to the full documentation for precise points. If you are reading this paragraph, you already have the tar manual in some form. This manual is available in printed form, as a kind of small book. It may printed out of the GNU tar distribution, provided you have TeX already installed somewhere, and a laser printer around. Just configure the distribution, execute the command `make dvi', then print `doc/tar.dvi' the usual way (contact your local guru to know how). If GNU tar has been conveniently installed at your place, this manual is also available in interactive, hypertextual form as an Info file. Just call `info tar' or, if you do not have the info program handy, use the Info reader provided within GNU Emacs, calling `tar' from the main Info menu.

Checking tar progress

Typically, tar performs most operations without reporting any information to the user except error messages. When using tar with many options, particularly ones with complicated or difficult-to-predict behavior, it is possible to make serious mistakes. tar provides several options that make observing tar easier. These options cause tar to print information as it progresses in its job, and you might want to use them just for being more careful about what is going on, or merely for entertaining yourself. If you have encountered a problem when operating on an archive, however, you may need more information than just an error message in order to solve the problem. The following options can be helpful diagnostic tools.

Normally, the `--list' (`-t') command to list an archive prints just the file names (one per line) and the other commands are silent. When used with most operations, the `--verbose' (`-v') option causes tar to print the name of each file or archive member as it is processed. This and the other options which make tar print status information can be useful in monitoring tar.

With `--create' (`-c') or `--extract' (`-x'), `--verbose' (`-v') used once just prints the names of the files or members as they are processed. Using it twice causes tar to print a longer listing (reminiscent of `ls -l') for each member. Since `--list' (`-t') already prints the names of the members, `--verbose' (`-v') used once with `--list' (`-t') causes tar to print an `ls -l' type listing of the files in the archive. The following examples both extract members with long list output:

tar --extract --file=archive.tar --verbose --verbose
tar xvv archive.tar

Verbose output appears on the standard output except when an archive is being written to the standard output, as with `tar --create --file=- --verbose' (`tar cfv -', or even `tar cv'---if the installer let standard output be the default archive). In that case tar writes verbose output to the standard error stream.

The `--totals' option--which is only meaningful when used with `--create' (`-c')---causes tar to print the total amount written to the archive, after it has been fully created.

The `--checkpoint' option prints an occasional message as tar reads or writes the archive. In fact, it print directory names while reading the archive. It is designed for those who don't need the more detailed (and voluminous) output of `--block-number' (`-R'), but do want visual confirmation that tar is actually making forward progress.

@FIXME{There is some confusion here. It seems that -R once wrote a message at `every' record read or written.}

The `--show-omitted-dirs' option, when reading an archive--with `--list' (`-t') or `--extract' (`-x'), for example--causes a message to be printed for each directory in the archive which is skipped. This happens regardless of the reason for skipping: the directory might not have been named on the command line (implicitly or explicitly), it might be excluded by the use of the `--exclude=pattern' option, or some other reason.

If `--block-number' (`-R') is used, tar prints, along with every message it would normally produce, the block number within the archive where the message was triggered. Also, supplementary messages are triggered when reading blocks full of NULs, or when hitting end of file on the archive. As of now, if the archive if properly terminated with a NUL block, the reading of the file may stop before end of file is met, so the position of end of file will not usually show when `--block-number' (`-R') is used. But this may change in the future: there are cases where GNU tar should drain the archive before exiting, while it currently does not.

This option is especially useful when reading damaged archives, since it helps pinpoint the damaged sections. It can also be used with `--list' (`-t') when listing a file-system backup tape, allowing you to choose among several backup tapes when retrieving a file later, in favor of the tape where the file appears earliest (closest to the front of the tape). @FIXME-xref{when the node name is set and the backup section written}.

Asking for Confirmation During Operations

Typically, tar carries out a command without stopping for further instructions. In some situations however, you may want to exclude some files and archive members from the operation (for instance if disk or storage space is tight). You can do this by excluding certain files automatically (see section Choosing Files and Names for tar), or by performing an operation interactively, using the `--interactive' (`-w') option. tar also accepts `--confirmation' for this option.

When the `--interactive' (`-w') option is specified, before reading, writing, or deleting files, tar first prints a message for each such file, telling what operation it intends to take, then asks for confirmation on the terminal. 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. To confirm the action, you must type a line of input beginning with `y'. If your input line begins with anything other than `y', tar skips that file.

If tar is reading the archive from the standard input, tar opens the file `/dev/tty' to support the interactive communications.

Verbose output is normally sent to standard output, separate from other error messages. However, if the archive is produced directly on standard output, then verbose output is mixed with errors on stderr. Producing the archive on standard output may be used as a way to avoid using disk space, when the archive is soon to be consumed by another process reading it, say. Some people felt the need of producing an archive on stdout, still willing to segregate between verbose output and error output. A possible approach would be using a named pipe to receive the archive, and having the consumer process to read from that named pipe. This has the advantage of letting standard output free to receive verbose output, all separate from errors.

Verifying Data as It is Stored

Attempt to verify the archive after writing.

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.

You can insure the accuracy of an archive by comparing files in the system with archive members. tar can compare an archive to the file system as the archive is being written, to verify a write operation, or can compare a previously written archive, to insure that it is up to date.

To check for discrepancies in an archive immediately after it is written, use the `--verify' (`-W') option in conjunction with the `--create' (`-c') operation. When this option is specified, tar checks archive members against their counterparts in the file system, and reports discrepancies on the standard error. In multi-volume archives, each volume is verified after it is written, before the next volume is written.

To verify an archive, you must be able to read it from before the end of the last written entry. This option is useful for detecting data errors on some tapes. Archives written to pipes, some cartridge tape drives, and some other devices cannot be verified.

One can explicitely compare an already made archive with the file system by using the `--compare' (`-d') option, instead of using the more automatic `--verify' (`-W') option. See section Comparing Archives Members with the File System.

Write Protection

All tapes and disks can be write protected, to protect data on them from being changed. Once an archive is written, you should write protect the media to prevent the archive from being accidently overwritten or deleted. (This will protect the archive from being changed with a tape or floppy drive--it will not protect it from magnet fields or other physical hazards).

The write protection device itself is usually an integral part of the physical media, and can be a two position (write enabled/write disabled) switch, a notch which can be popped out or covered, a ring which can be removed from the center of a tape reel, or some other changeable feature.

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