NAME

tar − tape archiver

SYNOPSIS

tar [ key ] [ name ... ]

DESCRIPTION

tar saves and restores multiple files on a single file (usually a magnetic tape, but it can be any file).  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. 

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

r The named files are written on the end of the tape.  Note the r option cannot be implemented on QIC Cartridge drives like that on the Titan. See LIMITATIONS section below. 

x The named files are extracted from the tape.  If the 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 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 one overwrites all earlier. 

t The names of the specified files are listed each time they occur on the tape.  If no file argument is given, all of the names on the tape are listed. 

u The named files are added to the tape if either they are not already there or have been modified since last put on the tape.  Note the u option cannot be implemented on QIC Cartridge drives like that on the Titan. See LIMITATIONS section below. 

c Create a new tape; writing begins on the beginning of the tape instead of after the last file.  This command implies r. 

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

o On output, tar normally places information specifying owner and modes of directories in the archive.  Former versions of tar, when encountering this information will give error message of the form
"<name>/: cannot create". 
This modifier will suppress the directory information. On input, the owner of the files will be the effective UID of the user who is extracting the files. This is the default action. If the UID is root, and this flag is not set, the creator of the archive becomes the owner of the extracted files. This modifier can be set to enable root ownership of the extracted files.

p This modifier says to restore files to their original modes, ignoring the present umask(2). Setuid and sticky information will also be restored to the super-user.

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

v Normally tar does its work silently.  The v (verbose) option makes tar print the name of each file it treats preceded by the function letter.  With the t function, the verbose option gives more information about the tape entries than just their names. 

w tar prints the action to be taken followed by file name, then wait for user confirmation. If a word beginning with ‘y’ is given, the action is done. Any other input means don’t do it. 

f tar 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 -)

b tar uses the next argument as the blocking factor for tape records. The default is 20 (the maximum). This option 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’). 

l tells tar to complain if it cannot resolve all of the links to the files dumped.  If this is not specified, no error messages are printed. 

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

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

I tar uses the next argument as a filename that contains a list of files for tar to write to an archive.  The list consists of one file per line.  Some options are allowed in the file list, discussed below.  The I keyletter is ignored when reading an archive. 

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

C If a file name is preceded by −C, then 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

tar c -C /usr include -C / etc

If the I keyletter is used, each filename in the list of files may have one of the following options preceding it (separated by a space): −C has the same meaning as above, causing a chdir to the named directory.  −d forces a particular directory to be written without getting its contents.  It is necessary to list a directory in this manner before listing all the files in that directory.  −h and +h override the non-existence or existence of the h keyletter on the command line.  The h keyletter sets a flag telling tar to follow symbolic links.  The −h option has the same effect on a per-file basis, or sets the flag for subsequent files if on a line by itself.  The +h option resets the flag either for a particular file or for subsequent files in the same manner. 

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

FILES

/dev/rmt? 
/tmp/tar∗

SEE ALSO

tar(5)

DIAGNOSTICS

Complaints about bad key characters and tape read/write errors. 
Complaints if enough memory is not available to hold the link tables.

LIMITATIONS

It is not possible to implement the r and u options on QIC cartridge tape drives because 1) the tape drive hardware is not capable of erasing a single track, and 2) the write head is not capable of changing a "1" to a "0" or to change a "0" to a "1". 

The QIC drives have one erase head that erases all 9 tracks at the same time.  The "erased" state is intermediate between the "1" state and the "0" state.  The drives have a one write head that can move up and down across the 9 tracks. The write head is only powerful enough to change a bit from the "erased" state to either the "1" or "0" state. 

BUGS

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.  When extracting tapes created with the r or u options, directory modification times may not be set correctly. 
The current limit on file name length is 100 characters.

September 02, 1992