tar -- tape archiver; manipulate "tar" archive files
tar [[-]bundled-options Args] [gnu-style-flags]
[filenames | -C directory-name] ...
Tar is short for ``tape archiver'', so named for historical reasons; the
tar program creates, adds files to, or extracts files from an archive
file in tar format, called a tarfile. A tarfile is often a magnetic
tape, but can be a floppy diskette or any regular disk file.
The first argument word of the tar command line is usually a command word
of bundled function and modifier letters, optionally preceded by a dash;
it must contain exactly one function letter from the set A, c, d, r, t,
u, x, for append, create, difference, replace, table of contents, update,
and extract (further described below). The command word can also contain
other function modifiers described below, some of which will take arguments
from the command line in the order they are specified in the command
word (review the EXAMPLES section). Functions and function modifiers
can also be specified with the GNU argument convention (preceded by
two dashes, one function or modifier per word. Command-line arguments
that specify files to add to, extract from, or list from an archive may
be given as shell pattern matching strings.
Exactly one of the following functions must be specified.
-A
--catenate
--concatenate Append the contents of named file, which must itself be a
tar archive, to the end of the archive (erasing the old
end-of-archive block). This has the effect of adding the
files contained in the named file to the first archive,
rather than adding the second archive as an element of the
first. Note: This option requires a rewritable tarfile,
and therefore does not work on quarter-inch cartridge
tapes.
-c
--create Create a new archive (or truncates an old one) and writes
the named files to it.
-d
--diff
--compare Find differences between files in the archive and corresponding
files in the file system.
--delete Delete named files from the archive. (Does not work on
quarter-inch tapes).
-r
--append Append files to the end of an archive. (Does not work on
quarter-inch tapes).
-t
--list List the contents of an archive; if filename arguments are
given, only those files are listed, otherwise the entire
table of contents is listed.
-u
--update Append the named files if the on-disk version has a modification
date more recent than their copy in the archive
(if any). Does not work on quarter-inch tapes.
-x
--extract
--get Extract files from an archive. The owner, modification
time, and file permissions are restored, if possible. If
no file arguments are given, extract all the files in the
archive. If a filename argument matches the name of a
directory on the tape, that directory and its contents are
extracted (as well as all directories under that directory).
If the archive contains multiple entries corresponding
to the same file (see the --append command
above), the last one extracted will overwrite all earlier
versions.
The other options to tar may be combined arbitrarily; single-letter
options may be bundled in with the command word. Verbose options which
take arguments will be followed by the argument; single-letter options
will consume successive command line arguments (see the EXAMPLES below).
--help Prints a message listing and briefly describing
all the command options to tar.
--atime-preserve Restore the access times on files which are written
to tape (note that this will change the
inode-change time!).
-b
--block-size number Sets the block size for reading or writing to
number * 512-byte blocks.
-B
--read-full-blocks Re-assemble short reads into full blocks (for
reading 4.2BSD pipes).
-C directory
--directory directory Change to directory before processing the remaining
arguments.
--checkpoint Print number of buffer reads/writes while reading/writing
the archive.
-f [hostname:]file
--file [hostname:]file Read or write the specified file (default is
/dev/sa0). If a hostname is specified, tar will
use rmt(8) to read or write the specified file on
a remote machine. ``-'' may be used as a filename,
for reading or writing to/from stdin/stdout.
--force-local Archive file is local even if it has a colon.
-F file
--info-script file
--new-volume-script file
Run a script at the end of each archive volume
(implies -M).
--fast-read Stop after all non-wildcard extraction targets
have been found in the archive.
-G
--incremental Create/list/extract old GNU-format incremental
backup.
-g file
--listed-incremental file
Create/list/extract new GNU-format incremental
backup.
-h
--dereference Don't write symlinks as symlinks; write the data
of the files they name.
-i
--ignore-zeros Ignore blocks of zeroes in archive (usually means
End-Of-File).
--ignore-failed-read Don't exit with non-zero status on unreadable
files.
-j
-y
--bzip
--bzip2
--bunzip2 Filter the archive through bzip2(1).
-k
--keep-old-files Keep files which already exist on disk; don't
overwrite them from the archive.
-K file
--starting-file file Begin at file in the archive.
-l
--one-file-system Stay in local file system when creating an archive
(do not cross mount points).
-L number
--tape-length number Change tapes after writing number * 1024 bytes.
-m
--modification-time Don't extract file modified time.
-M
--multi-volume Create/list/extract multi-volume archive.
-n
--norecurse Don't recurse into subdirectories when creating.
--volno-file file File name with volume number to start with.
-N date
--after-date date
--newer date Only store files with creation time newer than
date.
--newer-mtime date Only store files with modification time newer
than date.
-o
--old-archive
--portability Write a V7 format archive, rather than POSIX format.
-O
--to-stdout Extract files to standard output.
-p
--same-permissions
--preserve-permissions Extract all protection information.
--preserve Has the effect of -p -s.
-P
--absolute-paths Don't strip leading `/' from file names.
-R
--record-number Show record number within archive with each message.
--remove-files Remove files after adding them to the archive.
-s
--same-order
--preserve-order List of names to extract is sorted to match archive.
--show-omitted-dirs Show directories which were omitted while processing
the archive.
-S
--sparse Handle ``sparse'' files efficiently.
-T file
-I file
--files-from file Get names of files to extract or create from
file, one per line.
--null Modifies behavior of -T to expect null-terminated
names; disables -C.
--totals Prints total bytes written with --create.
-U
--unlink
--unlink-first Unlink files before creating them.
-v
--verbose Lists files written to archive with --create or
extracted with --extract; lists file protection
information along with file names with --list.
-V volume-name
--label volume-name Create archive with the given volume-name.
--version Print tar program version number.
-w
--interactive
--confirmation Ask for confirmation for every action.
-W
--verify Attempt to verify the archive after writing it.
--exclude pattern Exclude files matching the pattern (don't extract
them, don't add them, don't list them).
-X file
--exclude-from file Exclude files listed in file.
-Z
--compress
--uncompress Filter the archive through compress(1).
-z
--gzip
--gunzip Filter the archive through gzip(1).
--use-compress-program program
Filter the archive through program (which must
accept -d to mean ``decompress'').
--block-compress Block the output of compression program for tapes
or floppies (otherwise writes will be of odd
length, which device drivers may reject).
-[0-7][lmh] Specify tape drive and density.
The environment variable TAR_OPTIONS can hold a set of default options
for tar. These options are interpreted first and can be overwritten by
explicit command line parameters.
To create an archive on tape drive /dev/sa0 with a block size of 20
blocks, containing files named bert and ernie, you can enter
tar cfb /dev/sa0 20 bert ernie
or
tar --create --file /dev/sa0 --block-size 20 bert ernie
Note that the -f and -b flags both require arguments, which they take
from the command line in the order they were listed in the command word.
Because /dev/sa0 is the default device, and 20 is the default block size,
the above example could have simply been
tar c bert ernie
To extract all the C sources and headers from an archive named
backup.tar, type
tar xf backup.tar '*.[ch]'
Note that the pattern must be quoted to prevent the shell from attempting
to expand it according the files in the current working directory (the
shell does not have access to the list of files in the archive, of
course).
To move file hierarchies, use a command line like this:
tar -cf - -C srcdir . | tar xpf - -C destdir
To create a compressed archive on diskette, using gzip(1), use a commandline
like
tar --block-compress -z -c -v -f /dev/fd1a -b 36 tar/
Note that you cannot mix bundled flags and --style flags; you can use
single-letter flags in the manner above, rather than having to type
tar --block-compress --gzip --verbose --file /dev/fd1a --block-size
20 tar/
The above-created diskette can be listed with
tar tvfbz /dev/fd1a 36
To join two tar archives into a single archive, use
tar Af archive1.tar archive2.tar
which will add the files contained in archive2.tar onto the end of
archive1.tar (note that this can't be done by simply typing
cat archive2.tar >> archive1.tar
because of the end-of-file block at the end of a tar archive).
To archive all files from the directory srcdir, which were modified after
Feb. 9th 1997, 13:00 h, use
tar -c -f backup.tar --newer-mtime 'Feb 9 13:15 1997' srcdir/
Other possible time specifications are `02/09/97 13:15', `1997-02-09
13:15', `13:15 9 Feb 1997', `9 Feb 1997 13:15', `Feb. 9, 1997 1:15pm',
`09-Feb', `3 weeks ago' or `May first Sunday'. To specify the correct
time zone use either e.g. `13:15 CEST' or `13:15+200'.
The tar program examines the following environment variables.
POSIXLY_CORRECT Normally, tar will process flag arguments that appear in
the file list. If set in the environment, this causes
tar to consider the first non-flag argument to terminate
flag processing, as per the POSIX specification.
SHELL In interactive mode, a permissible response to the
prompt is to request to spawn a subshell, which will be
/bin/sh unless the SHELL variable is set.
TAPE Changes tar's default tape drive (which is still overridden
by the -f flag).
TAR_RSH The TAR_RSH environment variable allows you to override
the default shell used as the transport for tar.
/dev/sa0 The default tape drive.
The -y is a FreeBSD localism. The GNU tar maintainer has now chosen -j
as the offical bzip2(1) compression option in GNU tar 1.13.18 and later.
The -I option is for compatibility with Solaris's tar.
bzip2(1), compress(1), gzip(1), pax(1), rmt(8)
The tar format has a rich history, dating back to Sixth Edition UNIX.
The current implementation of tar is the GNU implementation, which originated
as the public-domain tar written by John Gilmore.
A cast of thousands, including [as listed in the ChangeLog file in the
source] John Gilmore (author of original public domain version), Jay
Fenlason (first GNU author), Joy Kendall, Jim Kingdon, David J.
MacKenzie, Michael I Bushnell, Noah Friedman, and innumerable others who
have contributed fixes and additions.
Man page obtained by the FreeBSD group from the NetBSD 1.0 release.
The -C feature does not work like historical tar programs, and is probably
untrustworthy.
The -A command should work to join an arbitrary number of tar archives
together, but it does not; attempting to do so leaves the end-of-archive
blocks in place for the second and subsequent archives.
The tar file format is a semi fixed width field format, and the field for
device numbers were designed for 16 bit (8 major, 8 minor) and cannot
absorb our 32 bit (8 major, 16+8 minor) numbers.
FreeBSD 5.2.1 December 23, 2000 FreeBSD 5.2.1 [ Back ] |
