NAME

tar − tape archiver

SYNOPSIS

tar [ key ] [ option ] [ files ]

DESCRIPTION

Tar saves and restores multiple files on a single file—usually a magnetic tape, although the file can be an ordinary file in the file system.  Tar’s actions are controlled by the key argument.  The key is a string of characters containing at most one function letter and possibly one or more 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. 

Previous restrictions dealing with tar’s inability to properly handle blocked archives have been lifted. 

KEYS

Function Letters

The function portion of the key is specified by one of the following letters:

c Creates a new tape.  Begins writing on the beginning of the tape instead of after the last file.  This function automatically runs the r function. 

r Writes the named files on the end of the tape.  (This function is automatically run by the c function.)  r does not work on quarter-inch tape drives.  The QIC 02 industry-standard interface, which is the basis of the VME-QIC2 cartridge tape controller’s interface, prevents this function from working properly.  Running this command on a quarter-inch drive produces unpredictable results. 

t Lists the names of the specified files each time the names occur on the tape.  If no file argument is given, lists all the names on the tape. 

u Adds the named files to the tape if either they are not already there or have been modified since last put on the tape.  This command does not work on quarter-inch tape drives.  The QIC 02 industry-standard interface, which is the basis of the VME-QIC2 cartridge tape controller’s interface, prevents this function from working properly.  If you run this function on a quarter-inch drive, the results are unpredictable. 

x Extracts the named files from the tape.  If the named file matches a directory whose contents had been written onto the tape, this directory is recursively extracted.  If possible, tar restores the owner, modification time, and mode of the file.  If no file argument is given, the entire content of the tape is extracted.  Note that if multiple entries specifying the same file are on the tape, the last entry overwrites all the earlier entries. 

Function Modifiers

The following characters may be used in addition to the letter which selects the function desired. 

0, ..., 9 Selects an alternate drive on which the tape is mounted.  The default is drive 0 at 1600 bpi, which is normally /dev/rmt8. 

b Uses the next argument as the blocking factor for tape records.  The default is 20 (the maximum).  This modifier should only be used with raw magnetic tape archives (See f above).  The block size is determined automatically when reading tapes (key letters x and t). 

B Forces input and output blocking to 20 blocks per record.  This modifier was added so that tar can work across a communications channel where the blocking may not be maintained. 

f Uses the next argument as the name of the archive instead of /dev/rmt?.  If the name of the file 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 move hierarchies with the command

cd fromdir; tar cf − . | (cd todir; tar xf −)

h Forces tar to follow symbolic links as though they were normal files or directories.  Normally, tar does not follow symbolic links. 

l Prints an error message if tar cannot resolve all links to dumped files.  Unless you specify this modifier, tar will not report this inability to resolve links. 

m Tells tar not to restore the modification times.  The modification time will be the time of extraction. 

o Suppresses output of directory information.  If you do not use this modifier, tarplaces information specifying owner and modes of directories in the archive.  (Earlier versions of tar when encountering this information print error messages in the form:  "<name>/: cannot create".) 

p Restores files to their original modes, ignoring the present umask(2).  Restores setuid and sticky information to the super-user. 

s Swaps the low byte of each word with the high byte of that word. 

v Turns on verbose mode.  Normally tar does not print messages describing its work.  With this modifier, tar prints the name of each file it handles preceded by the function letter.  If you use both the v modifier and the t function, tar lists the name, permissions, uid, gid, size, and date of each files it handles. 

w Prints the action to be taken followed by the name of the file the action will affect, then waits for your confirmation before completing the action.  Typing tells tar to complete the action.  Any other response cancels the action. 

OPTIONS

−Cdir Performs a chdir(2) to the specified directory.  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

tar c -C /usr include -C / etc

FILES

/dev/rmt? 
/tmp/tar∗

SEE ALSO

tar(5)

DIAGNOSTICS

Tar prints messages about bad key characters and tape read/write errors.  If not enough memory is available to hold the link tables, tar prints an error message saying so. 

BUGS

There is no way to ask for the n-th occurrence of a file.

Tar handles tape errors ungracefully. 

The u function can be slow. 

The current limit on filename length is 100 characters. 

There is no way to follow symbolic links selectively. 

When extracting tapes created with the r or u functions, tar sometimes sets the directory modification times incorrectly. 

INTEGRATED SOLUTIONS 4.3 BSD  —  November 25, 1987