tar(C)

tar -- archive files

Syntax

tar [ key ] [ files ]

Description

tar saves and restores files to and from an archive medium; typically, this is a floppy disk, a tape, or a regular file.

The actions of tar are controlled by the key; this is a string of characters containing at most one function letter and possibly one or more function modifiers.

files specifies the files to be backed up or restored. If a directory name is specified, this implies that the files and the entire subdirectory tree of the directory are to be backed up or restored.

See ``Limitations'' for details of the restrictions imposed by the capabilities of tar.

Function letters

One of the following function letters must be specified:

c: Creates a new archive; writing begins at the beginning of the archive, instead of after the last file.
C: Creates a new archive as above, containing compressed files. The files to be archived should be compressed first using compress(C). When the archive is unpacked, tar will pipe the files through uncompress(C), expanding them (if necessary). Note that this function modifier has no effect on filenames. That is, files stored with a .Z suffix retain them when unpacked, even if they have been uncompressed.
r: The named files are written to the end of an existing archive. This function letter is only valid for appending files to disk archives. When specifying the absolute path of an archive device with the f function modifier, use the n function modifier to indicate that the device is not a magnetic tape.
This function letter cannot be used with tape devices.
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. This function letter cannot be used with tape devices.
x: The named files are extracted from the archive. If a named file matches a directory whose contents had 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 entire contents of the archive are extracted. Note that if several files with the same name are on the archive, the last one overwrites all earlier ones. There is no way to ask for the nth occurrence of a file.

Function modifiers

The following characters are used in addition to the key function letter:

0,...,9999

This numeric key selects the device on which the archive is mounted. The available numeric keys are defined in the file /etc/default/tar. A list of archive devices and their corresponding numeric keys can be displayed by entering tar without any arguments. The f function modifier is used to specify an archive device which is not in /etc/default/tar.

A

Suppresses absolute filenames by removing leading slash (/) characters from filenames. When used with the c, r, t and u function letters, the A function modifier prevents leading slashes being written to the archive headers. When used with the x function letter to extract files, arguments must be given as pathnames excluding the leading slash.

b

Causes tar to use the next argument as the blocking factor for archive records. The blocking factor is used to calculate the archive block size. This function modifier should only be used with archives on raw devices (see the f function modifier for how to select different devices).

The blocking factor is specified as a multiple of 512 bytes, from 1 (equivalent to an archive block size of 512 bytes) up to a maximum of 20 (equivalent to 10K). If the device is not a tape device, the blocking factor must be specified as an even number from 2 to 20. For example, to use a 9K block size with a floppy disk, specify a blocking factor of 18:

tar cvfb /dev/rfd0 18 file

The block size is determined automatically when reading tape archives.

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 function modifier is also specified on the command line.

f

Causes tar to use the next argument as the name of the archive instead of the default device listed 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 -)

F

Causes tar to use the next argument as the name of a file from which succeeding arguments are taken.

k

Causes tar to use the next argument as the size of an archive volume in kilobytes (KB). The minimum value allowed is 250. 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. To override the archive length value in the default file, specify 0 as the argument to k on the command line.

l

Tells tar to display 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 displayed.

L

Follow symbolic links and archive the contents of the regular files to which they ultimately point with the name of the topmost link. By default, tar archives symbolic links without following them unless you also specify the P function modifier.

m

Tells tar not to restore the modification times. The modification time of the file is the time of extraction.

n

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

o

Assign the user and group identifiers of the user to the files being extracted rather than those stored on the archive. This is the default behavior of tar. This function modifier cannot be combined with the p function modifier.

p

Extract the files using their original permissions if the user is not the super user. It is possible that the user may be unable to extract files because of the permissions associated with the files or directories being extracted.

The sense of this function modifier is reversed for root; the files will be extracted with user and group ownership by root. This function modifier cannot be combined with the function letter o.

P

Select the historical-compatibility mode of tar; do not archive symbolic links, information about directories, or empty directories. If you specify this function modifier but not the L function modifier, tar issues a warning message when it encounters a symbolic link, skips over the link, and continues with the rest of the files.

q

During extraction causes tar to exit immediately after each file on the command line has been extracted, rather than continuing to look for additional files of the same name.

T

Truncates filenames of greater than 14 characters on extraction. This is used for extracting files from EAFS-type filesystems that support long filenames (up to 255 characters long) to AFS-type filesystems that support maximum 14-character filenames.

v

Normally, tar does its work silently. The v (verbose) function modifier causes tar to display 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.

w

Causes tar to display 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''.

Default archive values

If no archive device is specified, either by using a numeric key or the f function modifier, tar looks for a line in the file /etc/default/tar beginning with the string archive=. Following this string are 4 fields, separated by spaces, which contain values for the device name, blocking factor, volume size, and device type. The blocking factor is used to calculate the archive block size; it is expressed as a multiple of 512 bytes. The volume size entry should be modified to reflect the size in kilobytes of the archive volume used. Note that a volume size of `0' indicates infinite volume length. The device type is set to y for tape devices; otherwise, it is set to n.

For example, the following is the default device entry from /etc/default/tar:

   archive=/dev/rfd096ds15 10 1200 n

This indicates that the default device is a floppy disk drive, accessed as a raw device with a blocking factor of 10 (equivalent to 5KB, or ten 512-byte disk blocks) and a volume size of 1200KB. Any default value may be overridden using the b and k function modifiers.

When a numeric key (# in the range 0-9999) is specified, the corresponding device attributes are read from the line beginning with archive#= in the file /etc/default/tar. The remainder of the line has the same format as for the default archive device in the same file.

The default file /etc/default/tar must exist if a device is not specified on the command line using the f function modifier.

Using absolute and relative pathnames

A critical consideration when creating a tar volume involves the use of absolute or relative pathnames. Consider the following tar command examples, as executed from the directory /u/target:

tar cv /u/target/arrow
tar cv arrow

The first command creates a tar volume with the absolute pathname: /u/target/arrow. The second yields a tar volume with a relative pathname: ./arrow. (The ./ is implicit and shown here as an example; ./ should not be specified when retrieving the file from the archive.) When restored, the first example results in the file arrow being written to the directory /u/target (if it exists and you have write permission) no matter what your working directory. The second example simply writes the file arrow to your present working directory.

Absolute pathnames specify the location of a file in relation to the root directory (/); relative pathnames are relative to the current directory. This must be taken into account when making a tar tape or disk. Backup volumes use absolute pathnames so that they can be restored to the proper directory. Use relative pathnames when creating a tar volume where absolute pathnames are unnecessary. If necessary, you can specify the A function modifier to override absolute pathnames.

Exit values

tar returns a value of 0 (zero) if it completes successfully; it returns a non-zero value if an error has occurred.

Diagnostics

Displays an error message about bad key characters and archive read/write errors.

Displays an error message if not enough memory is available to hold the link tables.

Examples

If the name of a floppy disk device is /dev/fd1, then a tar format file can be created on this device by entering:

tar cvfk /dev/fd1 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/fd1 and 360.

To display a listing of the archive, enter:

tar tvf /dev/fd1

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

tar xvf /dev/fd1

The above command extracts all files from the archive, using the exact same pathnames as used when the archive was created. Because of this behavior, it is normally best to save archive files with relative pathnames rather than absolute ones, since directory permissions may not let you read the files into the absolute directories specified. (See the A flag under ``Options''.)

In the above examples, the v (verbose) function modifier is used simply to confirm the reading or writing of archive files on the screen. Also, a regular file could be substituted for the floppy device /dev/fd1 shown in the examples.

If the default device were to be used for the above examples, the corresponding tar commands would be:

tar cvk 360 files
tar tv
tar xv

The tar commands for the device corresponding to 5 in the device table would be:

tar cv5k 360 files
tar tv5
tar xv5

tar can be used to create archives of compressed files that are automatically uncompressed when they are extracted. For example:

compress ./tmp/
tar Cvf tmpZ.tar ./tmp/

All the files in ./tmp are compressed, then the archive tmpZ.tar is created using the C function letter (instead of c). When the archive is unpacked, the files will automatically be uncompressed. Note that if the files that are archived have a .Z suffix, they will be extracted to destination files with the same name even though they are no longer compressed.

Limitations

tar cannot archive device special files. For this reason, it is not suitable for creating filesystem backups.

Prior to this release, tar could not archive symbolic links, information about directories, or empty directories but it could follow symbolic links if the L function modifier was specified. Use the P function modifier to tar if you want to create an archive that can be read by the previous version of tar.

The limit on pathname length is 99 characters for archiving files. tar can read ptar archives with pathnames up to 255 characters long if specified without the P function modifier.

When extracting from an archive, if several files with the same name are on the archive, the last one overwrites all earlier ones. There is no way to ask for the nth occurrence of a file.

Archives created with the C function letter may be incompatible with other archivers and implementations of tar on other systems.

Note that the u function letter can be slow.

tar does not verify the selected media type.

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.

Files

/usr/bin/tar: tar executable file
/etc/default/tar: default values of device names, blocking factors, volume sizes, and device type
/tmp/tar: temporary work files used by tar

Open UNIX 8 compatibility notes

When running ACP on Open UNIX 8 and UnixWare 7 systems, set OSRCMDS=on to use the SCO OpenServer version of the <tar> command. This provides the expected behaviors for SCO OpenServer applications. The SCO OpenServer version of this command is also provided on Open UNIX 8 systems under the OSP feature See the Running SCO OpenServer Applications topic in the Open UNIX 8 documentation set.

Standards conformance

tar is conformant with:

AT&T SVID Issue 2;
X/Open CAE Specification, Commands and Utilities, Issue 4, 1992: note that this command is marked as to be withdrawn;
X/Open CAE Specification, Commands and Utilities, Issue 4, Version 2, 1994.: note that this command is marked as to be withdrawn.