NAME

tar − tape (and general purpose) archiver

USAGE

tar key [ blocksize ] [ name ] files

DESCRIPTION

Tar is a general-purpose archiving utility that

• bundles multiple files into a single archive file,

• restores to the file system any or all of the files in this archive,

• (if run by super user) optionally changes permissions on the files. 

While tar is most often used to archive files on magnetic tape, it can also be used any time you need to bundle a number of files into one object for later reconstitution.  The key is a string of characters containing one function letter and optional function modifiers.  It controls what tar does with the files to be bundled or unbundled (restored).  Note that in both cases (archiving and restoring), use of a directory name as one of the files includes all files in that directory and any subdirectories it contains. 

FUNCTIONS

Archiving Files

The following key letters specify tar options associated with creating an archive file.  Unless otherwise specified (see OPTIONS below), the archive is written to the device file /dev/rmt8. 

c Create a new archive.  Writing begins at the beginning of the file. 

r Append to an archive file.  Writing begins at the end the file.  (Not supported by Apollo magtape driver.) 

u Add the named files to the archive only if they are not already there, or are there but have been modified since they were last archived.  (Not supported by Apollo magtape driver.) 

Restoring Files

The following key letters specify tar options associated with restoration of selected files from a tar archive file.  Unless otherwise specified, the archive from which files are restored is the device file /dev/rmt8.  Restored files are always written to the current directory. 

t List the names of all the files in the archive. 

x Extract the named files from the archive.  If one of the files is a directory, tar extracts the directory and all files and subdirectories it contains. 

Files are restored with the same permissions they had when they were archived, with the following exceptions. 

• Tar does not set the set-user-ID and set-group-ID bits unless you are the super-user. 

• When a restored file overwrites a file by the same name, the existing file’s permissions are retained. 

• If you own the file (or are the super-user), tar restores the owner, modification time, and mode of the file. 

If no files are specified, tar x extracts the entire contents of the archive.  Note that if several files with the same name are on the tape, the last one overwrites all earlier ones. 

OPTIONS

You may append one or more of the following characters to the function letter in the key. 

0-9 This option, valid only when writing archives to tape, specifies the tape drive on which the archive is mounted.  The default is drive 0, normally /dev/rmt8. 

B Force input and output blocking to 20 blocks per record.  This option helps tar work across a communications channel where blocking may not be maintained. 

b This option is valid only when writing archives to tape.  If the b option is present on the tar command line, the key must be followed by a space and an integer blocksize in the range 1-20.  This blocksize specifies the block length for tape records.  The default is 20, the maximum.  Any blocksize you specify must coincide with the block length in the magtape descriptor file for the device to which tar is writing the archive.  The block size is determined automatically when reading tapes (keyletters x and t).  When writing to a cartridge tape, you must specify a block length of 1.  This requirement applies only to cartridge tape.  If the f option is also present in the key, tar expects the name and blocksize arguments to occur in the same order as the f and b options.  (See examples.) 

f If the f option is present on the tar command line, the key must be followed by a space and the name of the archive you want tar to read from or write to.  If this option is omitted, the default archive is /dev/rmt8.  If name is given as a dash (−), tar writes to the standard output or reads from the standard input, as appropriate.  If the b option is also present in the key, tar expects the name and blocksize arguments to occur in the same order as the f and b options.  (See examples.) 

h Follow symbolic links when they are encountered during the archiving process.  There is no way to selectively follow symbolic links. 

o Do not set owner and permissions of archived directories. 

l Complain when a link to the file being archived cannot be resolved. 

m Do not restore the modification times.  The modification time of the file is set to the time it was restored from the archive. 

p Restore files with their original access modes, ignoring the present umask (2), and restore setuid to the super-user. 

v This option makes tar display the name of each file it archives or restores, preceded by a function letter that indicates what it is doing (or planning to do) with the file.  These function letters are a for “append to archive” and x for “extract from archive.” When combined with the t function, v makes tar print out a “long” listing for each file in the archive, rather than just the name. 

w This option makes tar display the action (see v above) it is about to take and the name of the file that will be affected, then wait for confirmation.  If you enter a word beginning with y, tar performs the specified action.  Any other input means “no”. 

EXAMPLES

tar cbf 1 /dev/rct8 /usr/you Writes the contents of /usr/you and all of its subdirectories to cartridge tape. 

tar cfb 1 /dev/rct8 /usr/you Won’t work.  Blocksize and archive file name must be in the same order as b and f option letters. 

tar xf /dev/rct8 Restores all of the files from /dev/rct8 to the filesystem, writing them into the current working directory. 

tar cf /tarfile /usr/you/src/*.c Bundles all files in /usr/you/src whose names end in “.c” into /tarfile. 

NOTES

Since the Apollo magnetic tape driver does not support the u and r functions, tar can only create new archives (tar c) if you’re writing to tape.  The block length is fixed at 10240 bytes for the files /dev/rmt8 and /dev/rmt12 and 512 bytes for the files /dev/rct8 and /dev/rct12.  If you need to change the block length, use the /com/edmtdesc (edit magtape descriptor) command. 

Tar provides no way to re-tension a cartridge tape — a common remedy for tape I/O errors.  If you suspect that the tape needs to be re-tensioned or rewound, use the command /com/rbak with the -reten (re-tension) or -rewind (rewind) option. 

Tar limits filename length to 100 characters, a limit which may affect recursive descent into deep hierarchies. 

FILES

/dev/rmt8 magtape, rewind on file close

/dev/rmt12 magtape, no rewind on file close

/dev/rct8 cartridge tape, rewind on file close

/dev/rct12 cartridge tape, no rewind on file close

/tmp/tar* temporary file

DIAGNOSTICS

Tar issues various complaints about bad key characters, tape read/write errors, and insufficient memory to hold the link tables. 

RELATED INFORMATION

mtio(4), /com/rbak, /com/edmtdesc