TAR(1) General Commands Manual TAR(1)
tar - create tape archives, and add or extract files
tar [ - ] c|r|t|u|x [ bBefFhilmopvwX014578 ] [ tarfile ]
[ blocksize ] [ exclude-file ] [ -I include-file ]
filename1 filename2 ... -C directory filenameN ...
tar archives and extracts multiple files onto a single tar, file ar-
chive, 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 appear-
ance of a directory name refers recursively to the files and subdirec-
tories of that directory.
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 argu-
ments 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.
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 block-
ing 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 omit-
ted, 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 directo-
ries 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 directo-
ries. 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 modi-
fication 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 dis-
plays 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
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 speci-
fied 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) opera-
tion, 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.
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
and all the other files in /usr/include ...
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% 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 specifi-
cally 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
You can extract files from the archive like this:
example% tar xvf /dev/rmt0 extract files from the archive
messages from tar
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 ar-
chive. 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:
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
Finally, here is an example using tar to transfer files across the Eth-
ernet. 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
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 specify-
ing the blocksize (20) with the b option. If you want to change the
blocksize, you must change the blocksize arguments both on the tar com-
mand and on the dd command.
Now, here is how to use tar to get files from a tape on the remote sys-
tem back to the local system:
example% rsh -n host dd if=/dev/rmt0 bs=20b | tar xvBfb - 20
messages from tar
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.
/dev/rmt? half-inch magnetic tape interface
/dev/rst? SCSI tape interface
TAPE If specified, in the environment, the value of TAPE indicates
the default tape device.
cpio(1), csh(1), mt(1), umask(2V), tar(5), dump(8), restore(8)
Neither the r option nor the u option can be used with quarter-inch ar-
chive 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 modi-
fication 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'`
16 February 1988 TAR(1)