NAME

tar − file archiver

SYNOPSIS

tar [ key ] [ files ]

DESCRIPTION

tar saves and restores files to and from an archive medium, which is typically a storage device such as a floppy disk, a tape, or a regular file.  Its 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.  Valid function letters are c, t, x, u, and r.  Other arguments to the command are files (or directory names) specifying which files are to be backed up or restored.  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 to the end of the archive.  (Refer to NOTES.) 

x The named files are extracted from the archive.  If a named file matches a directory whose contents have been written onto the archive, this directory is (recursively) extracted.  The owner, modification time, and mode are restored (if possible).  If no files argument is given, the contents of the archive are extracted.  Note that if several files with the same name are on the archive, the last file overwrites all earlier ones. 

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

u The named files are added to the archive if they are not already there, or if they have been modified since last written on that archive. 

c Creates a new archive; writing begins at the beginning of the archive, instead of after the last file. 

e Prevents files from being split across volumes (tapes or floppy disks).  If there is not enough room on the present volume for a given file, tar prompts for a new volume.  This is only valid when the −k option is also specified on the command line. 

The following characters may be used in addition to the letter that selects the desired function:

0,...,7 This modifier selects the drive on which the archive is mounted.  The default drive is 1. 

v Normally, tar does its work silently.  The v (verbose) option causes it to type the name of each file it treats, preceded by the function letter.  With the t function, v gives more information about the archive entries than just the name. 

o Causes the extracted files to assume the owner and group ID of the user running the program rather than those on the archive tape. 

w Causes tar to print the action to be taken, followed by the name of the file, and then wait for the user’s confirmation.  If a word beginning with “y” is given, the action is performed.  Any other input means “no.”

f Causes tar to use the next argument as the name of the archive instead of the default device in /etc/default/tar.  If the name of the file is a dash (−), tar writes to the standard output or reads from the standard input, whichever is appropriate.  Thus, tar can be used as the head or tail of a pipeline.  tar can also be used to move hierarchies with the command:

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

b Causes tar to use the next argument as the blocking factor for archive records.  The default is 2, the maximum is 20.  This option should only be used with raw magnetic tape archives (see f above).  The number of bytes in a block is BSIZE as defined in /usr/include/sys/param.h. 

F Causes tar to use the next argument as the name of a file from which succeeding arguments are taken.  The dash (−) is not a valid argument here. 

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

l Tells tar to print an error message if it cannot resolve all of the links to the files being backed up.  If l is not specified, no error messages are printed. 

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

k Causes tar to use the next argument as the size of an archive volume in kilobytes.  The minimum value allowed is 250.  This option is useful when the archive is not intended for a magnetic tape device, but for some fixed size device, such as floppy disk (see f above).  Very large files are split into “extents” across volumes.  When restoring from a multi­volume archive, tar only prompts for a new volume if a split file has been partially restored. 

n Indicates the archive device is not a magnetic tape.  The k option implies this.  Listing and extracting the contents of an archive are sped because tar can seek over files it wishes to skip.  Sizes are printed in kilobytes instead of tape blocks. 

p Indicates that files are extracted using their original permissions.  It is possible that a non-superuser may be unable to extract files because of the permissions associated with the files or directories being extracted. 

EXAMPLES

If the name of a floppy disk device is /dev/dsk/f1q15dt, a tar format file can be created on this device by typing

tar cvfk /dev/dsk/f1q15dt 360 files

where files are the names of files you want archived and 360 is the capacity of the floppy disk in kilobytes.  Note that arguments to key letters are given in the same order as the key letters themselves; thus, the fk key letters have corresponding arguments, /dev/dsk/f1q15dt and 360.  Note that if a file is a directory, the contents of the directory are archived recursively.  To print a listing of the archive, type

tar tvf /dev/dsk/f1q15dt

At some later time you may want to extract the files from the floppy archive.  You can do this by typing

tar xvf /dev/dsk/f1q15dt

The above command extracts all files from the archive using the same path names as those of the original archive. Because of this behavior, it is best to save archive files with relative path names rather than absolute ones since directory permissions may not let you read the files into the specified absolute directories. 

In the above examples, the v option is used to confirm the reading or writing of archive files on the screen.  Also, a normal file could be substituted for the floppy device, /dev/dsk/f1q15dt, in the examples. 

FILES

/etc/default/tarDefault devices

/tmp/tar∗

SEE ALSO

cpio(1), ls(1). 

DIAGNOSTICS

Prints an error message about bad key characters and archive read/write errors.  Prints an error message if not enough memory is available to hold the link tables.

NOTES

There is no way to ask for the nth occurrence of a file.

The u option can be slow. 

The b option should not be used with archives that are going to be updated.  If the archive is on a disk file, the b option should not be used at all because updating an archive stored on a disk can destroy it.  To update (r or u option) a tar archive, do not use raw magtape and do not use the b option.  This applies both when updating and when first creating an archive. 

For streaming tape devices, the r option does not work due to hardware ­limitations. 

The limit on file name length is 100 characters. 
When archiving a directory that contains subdirectories, tar will only access those subdirectories that are within 17 levels of nesting.  Subdirectories at higher levels will be ignored after tar displays an error message. 

Systems with 1K byte file systems cannot specify raw disk devices unless the b option is used to specify an even number of blocks.  This means that you cannot update a raw-mode disk partition. 

Don’t do:

tar xfF − −

This would imply taking two things from the standard input at the same time. 

ADDED VALUE

This entry, supplied by SunSoft, Inc., contains enhancements to UNIX ­System V. 

\*U  —  Version 1.0