TAR (1)

NAME

tar - tape archiver

Synopsis
Description
Examples
Environment Variables
Files
See Also
Diagnostics
Notes

SYNOPSIS

tar [ key ] [ files ]

DESCRIPTION

Tar saves and restores files on magtape or other media. 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. Other arguments to the command are file or directory names specifying which files are to be dumped 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; use of the leading hyphen is optional:

-r The named files are written on the end of the tape. The -c function implies this.

-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 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. Existing target files are removed before the file in the archive is extracted.

-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.

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

0...9 This modifier selects the drive on which the tape (or other media) is mounted. Each number selects an 'archiveN=' entry in /etc/default/tar, which is followed by up to four fields: device name, blocking factor, size in kilobytes, and tape flag ('n' or 'N' for no tape). The entry 'archive=' is the default if neither this modifier nor the f key is given and the TAPE environment variable is not present. The following example sets up a tape, a 1.44 MB floppy drive for use with '0', using a blocking factor of 18, and a 1.2 MB floppy drive for use with '1', using a blocking factor of 15:
archive=/dev/rmt/c0s0 20 0
archive0=/dev/dsk/f03ht 18 1440 N
archive1=/dev/dsk/f15ht 15 1200 N

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 tape entries than just the name.

w causes tar to print the action to be taken followed by file name, then wait for user confirmation. If a word beginning with 'y' is given, the action is performed. Any other input means don't do it.

f causes tar to use the next argument as the name of the archive instead of the default (see the description for the '0...9' key above). 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 cf - . | (cd todir; tar xfp -)

b causes tar to use the next argument as the blocking factor for tape records. The default is device dependent. This option should only be used with raw magnetic tape archives (See f above).

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.

o causes tar to set the owner and group of restored files to those of the invoking user instead of those specified in the archive. This is the default unless the caller is the super-user.

p causes tar to set the permission bits of extracted files exactly to those given in the archive; normally, the current umask is applied.

i tells tar not to exit when a directory checksum error is encountered.

e tells tar to exit at several minor error conditions that normally cause only a warning.

n tells tar that the input file is not a tape. This causes block sizes to be reported in kilobytes instead of tape blocks with the 'v' modifier.

m causes tar not to restore modification times on extracted files; the modification time is the time when the file was restored.

h causes tar to store the target of a symbolic link in the archive and to follow symbolic links to directories instead of storing the link itself.

L Same as h.

A causes tar to strip a leading '/' when storing and restoring pathnames, i.e. to store and extract relative names instead of absolute ones.

k can be used to create and extract multi-volume archives. The next unevaluated argument is used as the maximum size in kilobytes for each part. If the archive does not fit on one medium, the user is prompted for the next. The same sizes must be given for creation and extraction of multi-volume archives.

B causes tar to repeat a read(2) operation if it gets fewer data than expected. This is useful when reading from pipes, network transports etc., and is enabled per default if reading from standard input, pipes, or sockets.

F specifies the name of a file with additional pathnames in the next unevaluated argument. Each line of this file must contain a pathname (without any leading or trailing white-space) that is put into the archive before further files specified on the command line.

X specifies the name of a file that contains pathnames to be excluded, in the same format as with F. This option may be specified multiple times, causing pathnames contained in any of the files to be excluded.

Tar also accepts the following options intermixed with the file names:

-C dir Change the working directory to dir before archiving the file name immediately following dir; name is interpreted relative to dir.

-I file Specifies a file with additional pathnames as described for the F key above, inserted at the current position in the archive.

The archive format written by tar is expected to be compatible with the 'Extended tar Format' as defined in IEEE Std. 1003.1, 1996, although the numerical uid and gid fields are always used for extraction, ignoring the symbolic uname and gname fields.

IEEE Std. 1003.1, 2001 pax format extended headers are created by tar under the following circumstances: A path name exceeds 255 bytes or does not contain a slash character at an appropriate position, and does not contain non-UTF-8 characters; the name of a linked file exceeds 100 bytes; a file is larger than 8 GB; a user or group ID exceeds the number 2097151. When updating GNU or old format archives, no extended headers are created and any path names are limited to 100 bytes. Most GNU extensions are supported when reading archives, and Sun extensions also for appending.

Multi-volume archives are splitted single-volume archives. For an archive created with
tar cfk /dev/dsk/f03ht 1440 input
it is thus possible to generate a single-volume archive by executing
dd if=/dev/dsk/f03ht bs=1k count=1440 >>singlevolume
once for each floppy disk.

On archives compressed with bzip2(1), compress(1), or gzip(1), the appropriate decompression program is run automatically with the t and x keys.

The following keys are supported as extensions:

z causes tar to pipe its output through gzip(1) when creating archives. When reading archives, this option is ignored.

j Similar to z, but using bzip2(1) as compression program.

Z Similar to z, but using compress(1) as compression program.

EXAMPLES

List the contents of a software distribution archive:
tar tvf distribution.tar.gz
Extract a software distribution archive, preserving file permissions, but setting the owner of all extracted files to the invoking user (even if invoked by root):
tar xfop distribution.tar.gz
Write the current directory to the default archive location:
tar c .
If the default location is a floppy drive, the archive is split across multiple volumes if necessary.
Create a gzip(1) compressed archive of the directory project and its contents:
tar cf - project | gzip -c > project.tar.gz

ENVIRONMENT VARIABLES

LANG, LC_ALL
See locale(7).

LC_TIME Used for the time string printed with when the keys tv are given.

SYSV3 If set, old tar format archives are created with 'c', and the meaning of the 'e' key is changed such that archiving is aborted if a file cannot fit on a single volume of a multi-volume archive.

TAPE Used as default archive if neither the 'f' nor the '0...9' keys are present.

FILES

/etc/default/tar
/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.

NOTES

There is no way to ask for the n-th occurrence of a file.
Tape errors are handled ungracefully.
The u option can be slow.
Use of the r and u options with tape devices requires drives capable of writing between filemarks.

Heirloom Toolchest

TAR (1)

3/1/05

Generated by a modified version of manServer 1.07 from tar.1 using man macros.

TAR (1)

NAME

CONTENTS

SYNOPSIS

DESCRIPTION

EXAMPLES

ENVIRONMENT VARIABLES

FILES

SEE ALSO

DIAGNOSTICS

NOTES

-r	The named files are written on the end of the tape. The -c function implies this.
-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 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. Existing target files are removed before the file in the archive is extracted.
-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.

0...9	This modifier selects the drive on which the tape (or other media) is mounted. Each number selects an 'archiveN=' entry in /etc/default/tar, which is followed by up to four fields: device name, blocking factor, size in kilobytes, and tape flag ('n' or 'N' for no tape). The entry 'archive=' is the default if neither this modifier nor the f key is given and the TAPE environment variable is not present. The following example sets up a tape, a 1.44 MB floppy drive for use with '0', using a blocking factor of 18, and a 1.2 MB floppy drive for use with '1', using a blocking factor of 15: archive=/dev/rmt/c0s0 20 0 archive0=/dev/dsk/f03ht 18 1440 N archive1=/dev/dsk/f15ht 15 1200 N
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 tape entries than just the name.
w	causes tar to print the action to be taken followed by file name, then wait for user confirmation. If a word beginning with 'y' is given, the action is performed. Any other input means don't do it.
f	causes tar to use the next argument as the name of the archive instead of the default (see the description for the '0...9' key above). 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 cf - . \| (cd todir; tar xfp -)
b	causes tar to use the next argument as the blocking factor for tape records. The default is device dependent. This option should only be used with raw magnetic tape archives (See f above).
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.
o	causes tar to set the owner and group of restored files to those of the invoking user instead of those specified in the archive. This is the default unless the caller is the super-user.
p	causes tar to set the permission bits of extracted files exactly to those given in the archive; normally, the current umask is applied.
i	tells tar not to exit when a directory checksum error is encountered.
e	tells tar to exit at several minor error conditions that normally cause only a warning.
n	tells tar that the input file is not a tape. This causes block sizes to be reported in kilobytes instead of tape blocks with the 'v' modifier.
m	causes tar not to restore modification times on extracted files; the modification time is the time when the file was restored.
h	causes tar to store the target of a symbolic link in the archive and to follow symbolic links to directories instead of storing the link itself.
L	Same as h.
A	causes tar to strip a leading '/' when storing and restoring pathnames, i.e. to store and extract relative names instead of absolute ones.
k	can be used to create and extract multi-volume archives. The next unevaluated argument is used as the maximum size in kilobytes for each part. If the archive does not fit on one medium, the user is prompted for the next. The same sizes must be given for creation and extraction of multi-volume archives.
B	causes tar to repeat a read(2) operation if it gets fewer data than expected. This is useful when reading from pipes, network transports etc., and is enabled per default if reading from standard input, pipes, or sockets.
F	specifies the name of a file with additional pathnames in the next unevaluated argument. Each line of this file must contain a pathname (without any leading or trailing white-space) that is put into the archive before further files specified on the command line.
X	specifies the name of a file that contains pathnames to be excluded, in the same format as with F. This option may be specified multiple times, causing pathnames contained in any of the files to be excluded.
Tar also accepts the following options intermixed with the file names:
-C dir	Change the working directory to dir before archiving the file name immediately following dir; name is interpreted relative to dir.
-I file	Specifies a file with additional pathnames as described for the F key above, inserted at the current position in the archive.
The archive format written by tar is expected to be compatible with the 'Extended tar Format' as defined in IEEE Std. 1003.1, 1996, although the numerical uid and gid fields are always used for extraction, ignoring the symbolic uname and gname fields.
IEEE Std. 1003.1, 2001 pax format extended headers are created by tar under the following circumstances: A path name exceeds 255 bytes or does not contain a slash character at an appropriate position, and does not contain non-UTF-8 characters; the name of a linked file exceeds 100 bytes; a file is larger than 8 GB; a user or group ID exceeds the number 2097151. When updating GNU or old format archives, no extended headers are created and any path names are limited to 100 bytes. Most GNU extensions are supported when reading archives, and Sun extensions also for appending.
Multi-volume archives are splitted single-volume archives. For an archive created with tar cfk /dev/dsk/f03ht 1440 input it is thus possible to generate a single-volume archive by executing dd if=/dev/dsk/f03ht bs=1k count=1440 >>singlevolume once for each floppy disk.
On archives compressed with bzip2(1), compress(1), or gzip(1), the appropriate decompression program is run automatically with the t and x keys.
The following keys are supported as extensions:
z	causes tar to pipe its output through gzip(1) when creating archives. When reading archives, this option is ignored.
j	Similar to z, but using bzip2(1) as compression program.
Z	Similar to z, but using compress(1) as compression program.

LANG, LC_ALL
	See locale(7).
LC_TIME	Used for the time string printed with when the keys tv are given.
SYSV3	If set, old tar format archives are created with 'c', and the meaning of the 'e' key is changed such that archiving is aborted if a file cannot fit on a single volume of a multi-volume archive.
TAPE	Used as default archive if neither the 'f' nor the '0...9' keys are present.