tar - create tape archives, and add or extract files

---

SYNOPSIS

DESCRIPTION

tar archives and extracts multiple files onto a single tar, file archive, called a tarfile. A tarfile is usually a magnetic tape, but it can be any file. tar's actions are controlled by the first argument, the key, a string of characters containing exactly one function letter from the set crtux, and one or more of the optional function modifiers listed below. Other arguments to tar are file or directory names that specify which files to archive or extract. In all cases, the appearance of a directory name refers recursively to the files and subdirectories of that directory.

FUNCTION LETTERS

c

Create a new tarfile and write the named files onto it.

r

Write the named files on the end of the tarfile. Note: this option does not work with quarter-inch archive tapes.

t

List the table of contents of the tarfile.

u

Add the named files to the tarfile if they are not there or if they have been modified since they were last archived. Note: this option does not work with quarter-inch archive tapes.

x

Extract the named files from the tarfile. If a named file matches a directory with contents written onto the tape, this directory is (recursively) extracted. The owner, modification time, and mode are restored (if possible). If no filename arguments are given, all files in the archive are extracted. Note: if multiple entries specifying the same file are on the tape, the last one overwrites all earlier versions.

FUNCTION MODIFIERS

b

Use the next argument as the blocking factor for tape records. The default blocking factor is 20 blocks. The block size is determined automatically when reading tapes (key letters x and t). This determination of the blocking factor may be fooled when reading from a pipe or a socket (see the B key letter below). The maximum blocking factor is determined only by the amount of memory available to tar when it is run. Larger blocking factors result in better throughput, longer blocks on nine-track tapes, and better media utilization.

B

Force tar to perform multiple reads (if necessary) so as to read exactly enough bytes to fill a block. This option exists so that tar can work across the Ethernet, since pipes and sockets return partial blocks even when more data is coming.

e

If any unexpected errors occur tar will exit immediately with a positive exit status.

f

Use the next argument as the name of the tarfile. If f is omitted, use the device indicated by the TAPE environment variable, if set. Otherwise, use /dev/rmt8 by default. If tarfile is given as `-', tar writes to the standard output or reads from the standard input, whichever is appropriate. Thus, tar can be used as the head or tail of a filter chain. tar can also be used to copy hierarchies with the command:

example% cd fromdir; tar cf - . | (cd todir; tar xfBp -)

F

With one F argument specified, exclude all directories named SCCS from tarfile. With two arguments FF, exclude all directories named SCCS, all files with .o as their suffix, and all files named errs, core, and a.out.

h

Follow symbolic links as if they were normal files or directories. Normally, tar does not follow symbolic links.

i

Ignore directory checksum errors.

l

Display error messages if all links to archived files cannot be resolved. If l is not used, no error messages are printed.

m

Do not extract modification times of extracted files. The modification time will be the time of extraction.

o

Suppress information specifying owner and modes of directories which tar normally places in the archive. Such information makes former versions of tar generate an error message like:

filename/: cannot create

when they encounter it.

p

Restore the named files to their original modes, ignoring the present umask.2v SetUID and sticky information are also extracted if you are the super-user. This option is only useful with the x key letter.

v

Verbose. Normally tar does its work silently; this option displays the name of each file tar treats, preceded by the function letter. When used with the t function, v displays the tarfile entries in a form similar to `ls -l'.

w

Wait for user confirmation before taking the specified action. If you use w, tar displays the action to be taken followed by the file name, and then waits for a y response to proceed. No action is taken on the named file if you type anything other than a line beginning with y.

X

Use the next argument as a file containing a list of named files (or directories) to be excluded from the tarfile when using the key letters c, x, or t. Multiple X arguments may be used, with one exclude file per argument.

014578

Select an alternate drive on which the tape is mounted. The numbers 2, 3, 6, and 9 do not specify valid drives. The default is /dev/rmt8.

If a file name is preceded by -I then the filename is opened. A list filenames, one per line, is treated as if each appeared separately on the command line. Be careful of trailing white space in both include and exclude file lists.

In the case where excluded files (see X option) also exist, excluded files take precedence over all included files. So, if a file is specified in both the include and exclude files (or on the command line), it will be excluded.

If a file name is preceded by -C in a c (create) or r (replace) operation, tar will perform a chdir (see csh.1 to that file name. This allows multiple directories not related by a close common parent to be archived using short relative path names. See EXAMPLES below.

Note: the -C option only applies to one following directory name and one following file name.

EXAMPLES

To archive files from /usr/include and from /etc, one might use:

example% tar c -C /usr include -C /etc .

If you get a table of contents from the resulting tarfile, you will see something like:

include/
include/a.out.h
and all the other files in /usr/include ...
/chown
and all the other files in /etc

Here is a simple example using tar to create an archive of your home directory on a tape mounted on drive /dev/rmt0:

example% cd
example% tar cvf /dev/rmt0 .
messages from tar

The c option means create the archive; the v option makes tar tell you what it is doing as it works; the f option means that you are specifically naming the file onto which the archive should be placed (/dev/rmt0 in this example).

Now you can read the table of contents from the archive like this:

example% tar  tvf  /dev/rmt0	display table of contents of the archive
(access  user-id/group-id	size 	mod. date 	filename)
rw-r--r-- 1677/40 	2123	Nov  7 18:15:1985	./archive/test.c
...
example%

You can extract files from the archive like this:

example% tar  xvf  /dev/rmt0	extract files from the archive
messages from tar
example%

If there are multiple archive files on a tape, each is separated from the following one by an EOF marker. tar does not read the EOF mark on the tape after it finishes reading an archive file because tar looks for a special header to decide when it has reached the end of the archive. Now if you try to use tar to read the next archive file from the tape, tar does not know enough to skip over the EOF mark and tries to read the EOF mark as an archive instead. The result of this is an error message from tar to the effect:

tar: blocksize=0

This means that to read another archive from the tape, you must skip over the EOF marker before starting another tar command. You can accomplish this using the mt.1 command, as shown in the example below. Assume that you are reading from /dev/nrmt0.

example% tar xvfp /dev/nrmt0 	read first archive from tape
messages from tar
example% mt fsf 1	skip over the end-of-file marker
example% tar xvfp /dev/nrmt0 	read second archive from tape
messages from tar
example%

Finally, here is an example using tar to transfer files across the Ethernet. First, here is how to archive files from the local machine (example) to a tape on a remote system (host):

example% tar cvfb  -  20 filenames | rsh host dd of=/dev/rmt0  obs=20b
messages from tar
example%

In the example above, we are creating a tarfile with the c key letter, asking for verbose output from tar with the v option, specifying the name of the output tarfile using the f option (the standard output is where the tarfile appears, as indicated by the `-' sign), and specifying the blocksize (20) with the b option. If you want to change the blocksize, you must change the blocksize arguments both on the tar command and on the dd command.

Now, here is how to use tar to get files from a tape on the remote system back to the local system:

example% rsh -n host dd if=/dev/rmt0 bs=20b | tar xvBfb - 20 filenames
messages from tar
example%

In the example above, we are extracting from the tarfile with the x key letter, asking for verbose output from tar with the v option, telling tar it is reading from a pipe with the B option, specifying the name of the input tarfile using the f option (the standard input is where the tarfile appears, as indicated by the `-' sign), and specifying the blocksize (20) with the b option.

FILES

/dev/rmt?

half-inch magnetic tape interface

/dev/rst?

SCSI tape interface

/tmp/tar*

ENVIRONMENT

TAPE

If specified, in the environment, the value of TAPE indicates the default tape device.

SEE ALSO

BUGS

Neither the r option nor the u option can be used with quarter-inch archive tapes, since these tape drives cannot backspace.

There is no way to ask for the nth occurrence of a file.

Tape errors are handled ungracefully.

The u option can be slow.

There is no way selectively to follow symbolic links.

When extracting tapes created with the r or u options, directory modification times may not be set correctly.

Files with names longer than 100 characters cannot be processed.

Filename substitution wildcards do not work for extracting files from the archive. To get around this, use a command of the form:

tar xvf... /dev/rst0 `tar tf... /dev/rst0 | grep 'pattern'`

Created by unroff & hp-tools. © somebody (See intro for details). All Rights Reserved. Last modified 11/5/97