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).  The key argument controlls tar’s actions. 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 (recursively) to the files and  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:

x Extract the named files from the tape.  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 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 earlier entries. 

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

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

c Create a new tape; writing starts at the beginning of the tape instead of after the last file.  This command implies the r option. 

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

In addition to the letter which selects the function desired the following characters may be used:

d On output, tar normally places information specifying owner and modes of directories in the archive.  Former versions of tar, when encountering this information print error messages of the form:
“<name>/: cannot create”. 
This option suppresses the printing of the directory information. This option implies the D option. 

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 create an ordinary file of the same name whose contents is the device number, in binary. This option suppresses the special file information.

p This option restores files to their original modes, ignoring the present umask(2). Setuid and sticky information are also 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 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 waits for user confirmation. If a word beginning with ‘y’ is given, the action is done.  Any other input means do not 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.  To move hierarchies, use the command

cd fromdir; tar cBf − . | (cd todir; tar xBf −)
 
To move hierarchies across systems, use:
 

xx system ’cd fromdir; tar cBf − .’ | (cd todir; tar xBf −)
 
To backup a hierarchy to a remote tape drive, use:
 

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

of=/dev/rmt1’
 
To extract from a remote tape, use:
 

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

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.  If the tape was written with a blocking factor that does not exceed the default for that device (20 or 400), the block size is determined automatically when reading a tape.  Use the default blocking factor with a cartridge tape.  Due to the blocking algorithm, a tar tape created by writing to the standard output should be read from standard input. 

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

m Do not 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 Force input and output blocking to 20 blocks per record.  This option allows tar to 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 Do not 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

Error messages about bad key characters and tape read/write errors. 

Error messages if enough memory is not available to hold the link tables. 

BUGS

Inserting a second tape could cause a system crash. 

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.  Archives cannot be spread over multiple tapes. 

Version 2.5r1  —  October 29, 1986