TAR(1) 1994 TAR(1)
NAME
tar - The GNU version of the sequential media archive
utility
SYNOPSIS
tar function [options] [files-list]
The function, options, and files-list components are
described below in sections with those names. There are
several conventions which may be followed in the
specification of arguments for tar. These are described
below under SYNTAX.
DESCRIPTION
The tar utility provides a way to store many files in an
archive (sometimes called a tar-file) which may be kept as
an ordinary file, stored on an I/O device such as tape or
disk, sent over a network, or piped to another program.
It is especially useful for making backup copies and for
packaging a set of files for convenience of handling or to
move them to another system.
When desired, copies of the archived files may be fully or
selectively retrieved from the archive by another
application of tar.
You may also use tar to append, delete, update or list
files in an archive or to compare an archive with the
current state of a filesystem subtree.
The tar utility is available for a wide variety of
operating systems and computer architectures which makes
it particularly useful for intersystem transfers. Source
code for tar is freely available to simplify porting it to
additional systems.
SYNTAX
Arguments to tar can be specified in several ways. This
is largely to accommodate different preferences in the
trade off between compactness on the one hand and improved
mnemonic value and accompanying verbosity on the other,
and to allow the continued use of old forms which have had
widespread use.
Compact Syntax
The normal compact command syntax conventions can be used:
The function designation conventionally appears
first and each option is separated by white space
and indicated by a `-' followed immediately by a
letter. Any required value for an option is
supplied by an argument which directly follows that
option;
18, June 1
TAR(1) 1994 TAR(1)
Multiple options can be combined behind one `-' as
long as they take no arguments.
Keyword Syntax
The more mnemonic but more verbose keyword system of
specifying arguments is structurally similar to the first
form above but each option is specified by a full word or
hyphenated phrase and the lead-in is a `--' instead of a
single `-'. All arguments are separated by white space
and each value directly follows the corresponding keyword.
Traditional Syntax
For compatibility with traditional tar programs, the
function and options may also be specified as
``keyletters'' in the first argument to tar omitting the
initial `-'. Any values required by the options occur as
the second, third, etc. arguments in the same order that
the keyletters appeared.
Examples:
The following examples show a sample command expressed in
each of the styles described above:
Compact:
tar -c -f arcname -v file1 file2
Keyword:
tar --create --file arcname --verbose file1 file2
Traditional:
tar cfv arcname file1 file2
FUNCTIONS
Exactly one of the functions in the following list must be
included. The list includes each of the compact forms
followed by the corresponding keyword or words.
-A, --catenate, --concatenate
Append existing tar-files to the archive.
-c, --create
Create a new archive containing the items specified
by the files-list.
-d, --diff, --compare
Find differences between the archive and the file
system.
Report differences in file size, mode, uid, gid,
and contents. If a file exists on the tape, but
not in the file system, that is reported.
-r, --append
Append list items to the end of the archive.
18, June 2
TAR(1) 1994 TAR(1)
-t, --list
List a table of contents of an existing archive.
If file names are specified, just list files
matching the specified names. The listing appears
on the standard output.
-u, --update
Only append list items that are newer than the
current copy in the archive.
-x, --extract, --get
Extract files from an existing archive. If a file-
list is specified, just extract files matching the
list items, otherwise extract all the files in the
archive.
To reduce the danger of accidental data loss the following
keyword function has no compact form.
--delete
Delete files-list from the archive (not for use on
mag tapes!).
OPTIONS
The corresponding keywords are shown following the compact
forms in the following list.
-b, --block-size N
Specify a blocking factor for the archive. The
block size will be N x 512 bytes. Larger blocks
typically run faster and let you fit more data on a
tape.
The default blocking factor is set when tar is
compiled, and is typically 20.
The maximum block size is limited by the lesser of
the amount of memory that can be allocated for a
block and the maximum block size that the device
containing the archive can read or write.
-B, --read-full-blocks
When reading an archive, reblock it as we read it.
Normally, tar reads each block with a single
read(2) system call. This does not work when
reading from a pipe or network socket under .
read(2) only gives as much data as has arrived at
the moment. With this option, it will do multiple
read(2)s to fill out to a record boundary, rather
than reporting an error. This option is the
default when reading an archive from standard
input, or over a network.
-C, --directory DIR
Change working directory to DIR. This is the only
option which may usefully appear more than once and
18, June 3
TAR(1) 1994 TAR(1)
may appear after the files-list begins. It changes
the working directory for locating items following
it in the list until another -C option occurs or
the end of the list is reached.
The -C and -T options may not be combined in a tar
command.
If you really need to process a file named `-C' it
can be referred to as `./-C' in the list.
-f, --file [HOSTNAME:]FILE
Use archive file or device FILE (the default is
taken from the environment variable TAPE if it is
defined, otherwise /dev/tape is used).
If the `-' character appears alone as the archive
name, it indicates that the standard input is to be
read as the archive or that standard output is to
be written as the archive according to the function
being performed.
-F, --info-script, --new-volume-script FILE
Run script at end of each volume (tape cartridge,
diskette, etc.) This option implies the multi-
volume option B-MP.
-G, --incremental
Create, extract, etc. old GNU-format
incremental backup.
-g, --listed-incremental FILE
Create, extract, etc. new GNU-format
incremental backup.
-h, --dereference
When creating an archive, if a symbolic link is
encountered, dump the file or directory to which it
points, rather than dumping it as a symbolic link.
-i, --ignore-zeros
When reading an archive, ignore blocks of zeros
appearing as headers in the archive. Normally such
a block of zeros indicates the end of the archive,
but in a damaged archive, or one which was created
by appending several archives, this option allows
tar to continue.
This option is not on by default because there is
garbage written after the zeroed blocks by some
versions of the tar program. Note that with this
option set, tar will read all the way to the end of
the file, eliminating some problems with multi-file
tapes.
-k, --keep-old-files
When extracting files from an archive, keep
existing files, rather than overwriting them with
18, June 4
TAR(1) 1994 TAR(1)
the version from the archive.
-K, --starting-file FILE
Begin at file FILE in the archive.
-l, --one-file-system
When dumping the contents of a directory to an
archive, stay within the local file system of that
directory. That is, do not process the contents of
a directory which is a filesystem mount point
encountered while processing a directory included
in the files-list.
This option only affects the files dumped because
they are in a dumped directory; files named on the
command line are always dumped, and they can be
from various file systems.
This is useful for making ``full dump'' archival
backups of a file system, as with the dump(8)
command. Files which are skipped due to this
option are mentioned on the standard error.
-L, --tape-length N
Change tape, diskette, etc. after writing each
N*1024 bytes.
-m, --modification-time
When extracting files from an archive, set each
file's modification timestamp to the current time,
rather than extracting each file's modification
timestamp from the archive.
-M, --multi-volume
Create, extract, etc. a multi-volume archive.
-N, --after-date, --newer DATE
Only store files newer than DATE.
-o, --old-archive, --portability
When creating an archive, write an old format
archive, which does not include information about
directories, pipes, fifos, contiguous files, or
device files, and specifies file ownership by uid's
and gid's rather than by user names and group
names. In most cases, a ``new'' format archive can
be read by an ``old'' tar program without serious
trouble, so this option should seldom be needed.
-O, --to-stdout
Extract files to standard output.
-p, --same-permissions, --preserve-permissions
When extracting files from an archive, restore them
to the same permissions that they had in the
archive. If -p is not specified, the current umask
18, June 5
TAR(1) 1994 TAR(1)
limits the permissions of the extracted files. See
umask(2).
-P, --absolute-paths
Don't strip leading `/'s from file names.
-R, --record-number
When writing each message for a file incorporated
into the archive show the record position, i.e.
which 512 byte block within the archive begins the
file record and contains the header information for
the file.
This option is especially useful when reading
damaged archives, since it helps to pinpoint the
damaged section.
-s, --same-order, --preserve-order
When using the -T option to specify the items to be
listed, compared or extracted from an archive, the
-s flag specifies that the list is sorted into the
same order as the archive. This allows a large
list to be used, even on small machines, because
the entire list need not be read into memory at
once.
Such a sorted list can easily be created by running
``tar -t'' on the archive and editing its output.
-S, --sparse
Handle sparse files efficiently.
-T, --files-from FILE
Get the files-list to extract, include, etc. from
file FILE (one item per line) instead of the
command line. FILE may not include occurrences of
the -C option.
If FILE is the `-' character alone the files-list
is taken from the standard input, one item per
line.
If the -T option is used, the files-list, if any,
appearing in the command will be ignored.
The -T and -C options may not be combined in a tar
command.
-v, --verbose
Provide a message for each file processed to or
from the archive.
If -v is used with the -t function the message for
each file is expanded to give details of file
ownership, size, modification date and permissions.
-V, --label NAME
Create archive with volume name NAME.
18, June 6
TAR(1) 1994 TAR(1)
-w, --interactive, --confirmation
Ask for confirmation for every action.
-W, --verify
Attempt to verify the archive after writing it.
-X, --exclude-from FILE
Exclude files listed in FILE.
-Z, --compress, --uncompress
Filter the archive through compress.
-z, --gzip, --ungzip
Filter the archive through gzip.
The following keyword options have no compact form:
--atime-preserve
Don't change access times on dumped files.
--checkpoint
List directory names while reading the archive.
--exclude FILE
Exclude file FILE.
--force-local
The archive file is local even if its name includes
a colon.
--ignore-failed-read
Don't exit with non-zero status on unreadable
files.
--preserve
Equivalent to both -p and -s options i.e.
--preserve-order --preserve-permissions.
--remove-files
Remove files after adding them to the archive.
--same-owner
Create extracted files with the same ownership.
--null Make the -T option read null-terminated names.
--totals
List total bytes written with --create.
--version
Display tar program version number.
--use-compress-program PROG
Filter the archive through PROG (which must accept
18, June 7
TAR(1) 1994 TAR(1)
the option -d to indicate decompression).
--block-compress
Block the output of the compression program for
tapes.
-[0-7][lmh]
This is an obsolete form used to specify tape drive
and density.
FILES LIST
The files-list may contain working directory changes and
the names of items which are to be archived, extracted,
etc. according to the function selected.
-C directory_name
This is an instruction to change the working
directory to the specified directory. Details
appear in the description of -C under OPTIONS.
file_name
A file name as an item implies only the processing
of the named file.
directory_name
A directory name as an item implies that the entire
filesystem subtree based there should be processed.
By default, if a full path name is specified when creating
an archive, it will be written to the archive without the
initial "/", to allow the files to be later read into a
different place than where they were dumped from, and a
warning will be printed.
If files are extracted from an archive which contains full
path names, they will be extracted relative to the current
directory and a warning message printed.
To modify the default behaviour use the -P or --absolute-
paths option.
When extracting, comparing or listing an archive, the
items in the files-list refer to records in the archive
and may contain wild card characters for filename
substitution using mostly the same forms as the shell, sh.
The shell actually matches each substring between ``/''s
separately, while tar matches the entire string at once,
so some anomalies will occur; e.g. ``*'' or ``?'' can
match a ``/''.
To specify a regular expression as an argument to tar,
quote it so the shell will not expand it.
FILES
/dev/tape the default tar archive file
18, June 8
TAR(1) 1994 TAR(1)
SEE ALSO
tar(5), shar(1), compress(1), ar(1), gzip(1), cpio(1),
dump(8), restore(8) rsh(1), dd(1), find(1)
AUTHOR
The GNU tar program is a product of the Free Software
Foundation and is distributed under their General Public
License.
This writeup was written by Thos Sumner for the 386BSD
distribution. It includes material from the manual page
for John Gilmore's public domain pdtar program on which
GNU tar is based.
18, June 9