NAME

tar − tape archiver

SYNOPSIS

tar [−]ctxru[ovwfbXlmhFpB014578i] [ tarfile ] [ blocksize ] [ exclude file ]

filename1 filename2 ... −C dir filenameN ...

DESCRIPTION

tar saves and restores multiple files on a single tarfile (usually a magnetic tape, but it can be any file).  tar’s actions are controlled by its first argument, the key, a string of characters containing exactly one function letter from the set rxtuc and one or more optional function modifiers.  Other arguments to tar are file or directory names specifying which files to dump or restore.  In all cases, appearance of a directory name refers to the files and (recursively) 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 that 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 whose contents had been written onto the tape, this directory is (recursively) extracted.  The owner, modification time, and mode are restored (if possible).  If no file arguments are given, the entire content of the tape is extracted.  Note that if multiple entries specifying the same file are on the tape, the last one overwrites all earlier versions.

t List all of the names on the tarfile. 

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

FUNCTION MODIFIERS

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. 

f Use the next argument as the name of the tarfile instead of /dev/rmt8.  If the name is ‘−’, tar writes to standard output or reads from 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:

tutorial% cd fromdir; tar cf − . | (cd todir; tar xfBp −)

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:
‘<name>/: cannot create’
when they encounter it.

v Normally tar does its work silently; the v (verbose) 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’. 

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. 

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. 

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

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 as their suffix, and all files named errs, core, and a.out. 

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

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

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

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. 

i Ignore directory checksum errors. 

If a file name is preceded by −C in a c (create) or r (replace) operation, tar will perform a chdir(2) to that file name.  This allows multiple directories not related by a close common parent to be archived using short relative path names.  For example, to archive files from /usr/include and from /etc, one might use:

tutorial%  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

Note that the −C option only applies to one following directory name and one following file name. 

EXAMPLES

Here is a simple example using tar to create an archive of your home directory onto /dev/rmt0:

tutorial%cdposition yourself in your home directory
tutorial%tar  cvf  /dev/rmt0  .create the archive
lots of messages from tar
tutorial%

The c option means create the archive; the v option makes tar tell you what it’s 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:

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

You can extract files from the archive like this:

tutorial%tar  xvf  /dev/rmt0extract files from the archive
lots of messages from tar
tutorial%

If there are multiple archive files on a tape, each is separated from the following one by an end-of-file marker.  tar does not read the end-of-file 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 doesn’t know enough to skip over the end-of-file mark and tries to read the end-of-file 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 end-of-file marker before starting another tar command.  You can achieve this via the mt command, as shown in the example below.  Assume that you are reading from /dev/nrmt0. 

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

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

tutorial%   tar cvfb  −  20  files  | rsh  krypton  dd of=/dev/rmt0  obs=20b
lots of messages from tar
tutorial%

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 via 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 (krypton) back to the local system (tutorial):

tutorial%   rsh  krypton  dd  if=/dev/rmt0  bs=20b | tar xvBfb  − 20  files
lots of messages from tar
tutorial%

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 via 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/rar?quarter-inch magnetic tape interface
/dev/rst?SCSI tape interface
/tmp/tar∗

SEE ALSO

tar(5), cpio(1), dump(8), restore(8)

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 n’th 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 that 100 characters cannot be processed. 

Filename substitution wildcards don’t 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’‘

Sun Release 3.2  —  Last change: 17 July 1986