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.  These files are dumped to tape in alphabetical order. 

A tar archive is a stream of 512-byte header structures which may be followed by file data rounded up to the next 512-byte boundary.  The end of the archive is signaled by two header structures beginning with null bytes. 

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.  The c function implies this.  This option cannot be used with cartridge tapes. 

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. 

X Like x but also takes the next argument as the root of a directory tree for comparison.  For each file to be extracted, if it is identical to the file in the corresponding position in the comparison tree, the existing file is linked to the new file.  Otherwise, the new file is extracted as a separate new file as usual. 

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. 

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

C Compare files on tape against existing files.  For each specified file, print a line with a key character followed by the file name. 

L linked to an earlier file on the tape
S symbolic link
B block special file
C character special file
P named pipe
? can’t read the disk file, so can’t compare
> disk file doesn’t exist
= files compare
! files don’t compare

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

d 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 option will suppress the directory information. This option implies −D. 

D On output, tar normally places information specifying the owner, modes, and device numbers of character and block special files and named pipes (fifos) in the archive.  Former versions of tar, when encountering this information will create an ordinary file of the same name whose contents is the device number, in binary. 
This option will suppress the special file information.

p This option 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, 1, 2, 3, 4, 5, 6, 7, 8, 9
This modifier selects an alternate drive on which the tape is mounted. The default is /dev/rmt1.

v Normally tar does its work silently.  The v (verbose) option make tar type 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 waits 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/rmt1. 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 cBf − . | (cd todir; tar xBf −)
 
Tar may be used to move hierarchies across systems via
 

xx system ’cd fromdir; tar cBf − .’ | (cd todir; tar xBf −)
 
Tar may also be used to backup a hierarchy to a remote tape drive via
 

tar cBf − fromdir | xx system ’dd ibs=10k obs=200k

of=/dev/rmt1’
 
or to extract from a remote tape drive via
 

xx system ’dd ibs=200k obs=10k if=/dev/rmt1’ | tar xBf −
 
Note that the xx command merges standard output with standard error so that if there are any error messages they will cause the second tar to fail, usually with a write error due to an attempt to write a record (the error message) whose size is not a multiple of 512.  This may be solved by using the Bourne shell’s capability to redirect just standard error on the remote system via
 

xx system ’cd fromdir;/bin/sh −c "tar cBf − . 2>/dev/console"’

| tar xBf −

b Tar uses the next argument as the blocking factor for tape records. The default is 400 for the cartridge tape, 1 for standard input and standard output, and 20 otherwise.  The block size is usually determined automatically when reading tapes if the tape was written with a blocking factor that does not exceed the default for that device (20 or 400).  The default blocking factor should be used for cartridge tape.  A tar tape created by writing to the standard output should be read from standard input, due to the blocking algorithm. 

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. 

e Force tar to continue reading past tape errors. 

L Force tar to follow symbolic links as if they were normal files or directories. 

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

R When extracting from tape, ignore leading slashes on file names, i.e. extract all files relative to the current directory. 

U For each file extracted, unlink existing file, if any. 

o Don’t chown (or chgrp) files. 

a Reset access times of input files after they have been copied to the archive. 

q Turn on debugging and extra error diagnostics.  Supplying this flag multiple times increases debugging level. 

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 a file name of − is given on the command line when making an archive then tar will read its standard input for a list of files to back up, one per line; the list is terminated by an EOF.  For example, to back up all files that have changed in the last week, one might use

find / −mtime −7 −print | tar ca −

FILES

/dev/rmt? 
/tmp/tar*

DIAGNOSTICS

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

BUGS

There is no way to ask for the n−th occurrence of a file.
The system must be rebooted after hard tape errors.
The u option can be slow. 
File name length is limited to 100 characters.
The data for a file with multiple links is output to tape with the first link encountered.   Thus, an attempt to extract a subsequent link by itself will not have the desired result.
The cartridge tape drive always reads and writes 512−byte records. Each tape must be created from scratch.  Files may not be appended, and archives cannot be spread over multiple tapes.

Version 2.3  —  July 04, 1985