394 lines
12 KiB
Groff
394 lines
12 KiB
Groff
.\" Copyright (c) 1991, 1992, 1993 Free Software Foundation -*- nroff -*-
|
|
.\" See /usr/src/gnu/COPYING for conditions of redistribution
|
|
.\"
|
|
.\" Written by John F. Woods <jfw@jfwhome.funhouse.com>
|
|
.\"
|
|
.\" $Id: tar.1,v 1.9 1997/06/05 23:12:13 max Exp $
|
|
.\"
|
|
.Dd August 6, 1994
|
|
.Os FreeBSD
|
|
.Dt TAR 1
|
|
.Sh NAME
|
|
.Nm tar
|
|
.Nd
|
|
tape archiver; manipulate "tar" archive files
|
|
.Sh SYNOPSIS
|
|
.Nm
|
|
.Op Cm Bq -
|
|
.Op Cm bundled-options
|
|
.Op Ar [gnu-style-flags]
|
|
.Op Ar tarfile
|
|
.Op Ar blocksize
|
|
.Op Ar exclude-file
|
|
.Op Ar filenames
|
|
.Op Fl C Ar directory-name
|
|
.Sh DESCRIPTION
|
|
.Nm
|
|
is short for
|
|
.Dq tape archiver,
|
|
so named for historical reasons; the
|
|
.Nm
|
|
program creates, adds files to, or extracts files from an archive file
|
|
in
|
|
.Dq tar
|
|
format, called a
|
|
.Ar tarfile .
|
|
A tarfile is often a magnetic tape, but can be a floppy diskette or any
|
|
regular disk file.
|
|
.Pp
|
|
The first argument word of the
|
|
.Nm
|
|
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
|
|
.Cm A ,
|
|
.Cm c ,
|
|
.Cm d ,
|
|
.Cm r ,
|
|
.Cm t ,
|
|
.Cm u ,
|
|
.Cm 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.
|
|
.Sh FUNCTIONS
|
|
Exactly one of the following functions must be specified.
|
|
.Pp
|
|
.Bl -tag -width "--concatenate" -compact
|
|
.It Fl A
|
|
.It Fl -catenate
|
|
.It Fl "-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.
|
|
.Em Note:
|
|
This option requires a rewritable tarfile,
|
|
and therefore does not work on quarter-inch cartridge tapes.
|
|
.It Fl c
|
|
.It Fl -create
|
|
Create a new archive (or truncates an old one) and writes the named files
|
|
to it.
|
|
.It Fl d
|
|
.It Fl -diff
|
|
.It Fl -compare
|
|
Find differences between files in the archive and corresponding files in
|
|
the file system.
|
|
.It Fl -delete
|
|
Delete named files from the archive (Does not work on quarter-inch tapes).
|
|
.It Fl r
|
|
.It Fl -append
|
|
Append files to the end of an archive (Does not work on quarter-inch tapes).
|
|
.It Fl t
|
|
.It Fl -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.
|
|
.It Fl u
|
|
.It Fl -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.
|
|
.It Fl x
|
|
.It Fl -extract
|
|
.It Fl -get
|
|
Extract files from an archive. The owner, modification time, and file
|
|
permissions are restored, if possible. If no
|
|
.Ar file
|
|
arguments are given, extract all the files in the archive. If a
|
|
.Ar 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
|
|
.Fl -append
|
|
command above), the last one extracted will overwrite all earlier versions.
|
|
.El
|
|
.Sh OPTIONS
|
|
The other options to
|
|
.Nm
|
|
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
|
|
.Sx EXAMPLES
|
|
below).
|
|
.Pp
|
|
.Bl -tag -width "--preserve-permissions" -compact
|
|
.It Fl -help
|
|
Prints a message listing and briefly describing all the command
|
|
options to tar.
|
|
.It Fl -atime-preserve
|
|
Restore the access times on files which are written to tape (note that
|
|
this will change the inode-change time!).
|
|
.It Fl b
|
|
.It Fl -block-size Ar number
|
|
Sets the block size for reading or writing to N 512-byte blocks.
|
|
.It Fl B
|
|
.It Fl -read-full-blocks
|
|
Re-assemble short reads into full blocks (for reading 4.2BSD pipes).
|
|
.It Fl C Ar directory
|
|
.It Fl -directory Ar directory
|
|
Change to
|
|
.Ar directory
|
|
for extraction.
|
|
.It Fl -checkpoint
|
|
Print directory names while reading the archive.
|
|
.It Fl f Ar [hostname:]file
|
|
.It Fl -file Ar [hostname:]file
|
|
Read or write the specified
|
|
.Ar file
|
|
(default is /dev/rst0). If a
|
|
.Ar hostname
|
|
is specified,
|
|
.Nm
|
|
will use
|
|
.Xr rmt 8
|
|
to read or write the specified
|
|
.Ar file
|
|
on a remote machine. "-" may be used is a filename, for reading
|
|
or writing to/from stdin/stdout.
|
|
.It Fl F Ar file
|
|
.It Fl -info-script Ar file
|
|
.It Fl -new-volume-script Ar file
|
|
Run a script at the end of each archive volume (implies
|
|
.Fl M ) .
|
|
.It Fl -fast-read
|
|
Stop after all non-wildcard extraction targets have been found
|
|
in the archive.
|
|
.It Fl G
|
|
.It Fl -incremental
|
|
Create/list/extract old GNU-format incremental backup.
|
|
.It Fl g Ar file
|
|
.It Fl -listed-incremental Ar file
|
|
Create/list/extract new GNU-format incremental backup.
|
|
.It Fl h
|
|
.It Fl -dereference
|
|
Don't write symlinks as symlinks; write the data of the files they name.
|
|
.It Fl i
|
|
.It Fl -ignore-zeros
|
|
Ignore blocks of zeroes in archive (usually means End-Of-File).
|
|
.It Fl -ignore-failed-read
|
|
Don't exit with non-zero status on unreadable files.
|
|
.It Fl k
|
|
.It Fl -keep-old-files
|
|
Keep files which already exist on disk; don't overwrite them from the archive.
|
|
.It Fl K Ar file
|
|
.It Fl -starting-file Ar file
|
|
Begin at
|
|
.Ar file
|
|
in the archive.
|
|
.It Fl l
|
|
.It Fl -one-file-system
|
|
Stay in local filesystem when creating an archive (do not cross mount
|
|
points).
|
|
.It Fl L Ar number
|
|
.It Fl -tape-length Ar number
|
|
Change tapes after writing N*1024 bytes.
|
|
.It Fl m
|
|
.It Fl -modification-time
|
|
Don't extract file modified time.
|
|
.It Fl M
|
|
.It Fl -multi-volume
|
|
Create/list/extract multi-volume archive.
|
|
.It Fl N Ar date
|
|
.It Fl -after-date Ar date
|
|
.It Fl -newer Ar date
|
|
Only store files newer than
|
|
.Ar date .
|
|
.It Fl o
|
|
.It Fl -old-archive
|
|
.It Fl -portability
|
|
Write a V7 format archive, rather than POSIX format.
|
|
.It Fl O
|
|
.It Fl -to-stdout
|
|
Extract files to standard output.
|
|
.It Fl p
|
|
.It Fl -same-permissions
|
|
.It Fl -preserve-permissions
|
|
Extract all protection information.
|
|
.It Fl -preserve
|
|
Has the effect of
|
|
.Fl p s.
|
|
.It Fl P
|
|
.It Fl -absolute-paths
|
|
Don't strip leading `/' from file names.
|
|
.It Fl R
|
|
.It Fl -record-number
|
|
Show record number within archive with each message.
|
|
.It Fl -remove-files
|
|
Remove files after adding them to the archive.
|
|
.It Fl s
|
|
.It Fl -same-order
|
|
.It Fl -preserve-order
|
|
List of names to extract is sorted to match archive.
|
|
.It Fl S
|
|
.It Fl -sparse
|
|
Handle "sparse" files efficiently.
|
|
.It Fl T Ar file
|
|
.It Fl -files-from Ar file
|
|
Get names of files to extract or create from
|
|
.Ar file ,
|
|
one per line.
|
|
.It Fl -null
|
|
Modifies behavior of
|
|
.Fl T
|
|
to expect null-terminated names; disables
|
|
.Fl C.
|
|
.It Fl -totals
|
|
Prints total bytes written with --create.
|
|
.It Fl v
|
|
.It Fl -verbose
|
|
Lists files written to archive with --create or extracted with --extract;
|
|
lists file protection information along with file names with --list.
|
|
.It Fl V Ar volume-name
|
|
.It Fl -label Ar volume-name
|
|
Create archive with the given
|
|
.Ar volume-name .
|
|
.It Fl -version
|
|
Print tar program version number.
|
|
.It Fl w
|
|
.It Fl -interactive
|
|
.It Fl -confirmation
|
|
Ask for confirmation for every action.
|
|
.It Fl W
|
|
.It Fl -verify
|
|
Attempt to verify the archive after writing it.
|
|
.It Fl -exclude Ar pattern
|
|
Exclude files matching the
|
|
.Ar pattern
|
|
(don't extract them, don't add them, don't list them).
|
|
.It Fl X Ar file
|
|
.It Fl -exclude-from Ar file
|
|
Exclude files listed in
|
|
.Ar file .
|
|
.It Fl Z
|
|
.It Fl -compress
|
|
.It Fl -uncompress
|
|
Filter the archive through
|
|
.Xr compress 1 .
|
|
.It Fl z
|
|
.It Fl -gzip
|
|
.It Fl -gunzip
|
|
Filter the archive through
|
|
.Xr gzip 1 .
|
|
.It Fl -use-compress-program Ar program
|
|
Filter the archive through
|
|
.Ar program
|
|
(which must accept
|
|
.Fl d
|
|
to mean ``decompress'').
|
|
.It Fl -block-compress
|
|
Block the output of compression program for tapes or floppies
|
|
(otherwise writes will be of odd length, which device drivers may reject).
|
|
.It Fl [0-7][lmh]
|
|
Specify tape drive and density.
|
|
.It Fl -norecurse
|
|
Don't recurse into subdirectories when creating.
|
|
.It Fl -unlink
|
|
Unlink files before creating them.
|
|
.El
|
|
.Sh EXAMPLES
|
|
To create an archive on tape drive /dev/rst0 with a block size of 20
|
|
blocks, containing files named "bert" and "ernie", you can enter
|
|
.Dl tar cfb /dev/rst0 20 bert ernie
|
|
or
|
|
.Dl tar --create --file /dev/rst0 --block-size 20 bert ernie
|
|
Note that the
|
|
.Fl f
|
|
and
|
|
.Fl b
|
|
flags both require arguments, which they take from the command line in
|
|
the order they were listed in the command word.
|
|
.Pp
|
|
Because /dev/rst0 is the default device, and 20 is the default block
|
|
size, the above example could have simply been
|
|
.Dl tar c bert ernie
|
|
.Pp
|
|
To extract all the C sources and headers from an archive named
|
|
"backup.tar", type
|
|
.Dl 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).
|
|
.Pp
|
|
To move file hierarchies, use a command line like this:
|
|
.Bd -literal
|
|
tar -cf - -C srcdir . | tar xpf - -C destdir
|
|
.Ed
|
|
.Pp
|
|
To create a compressed archive on diskette, using gzip, use a command-line like
|
|
.Dl tar --block-compress -z -c -v -f /dev/rfd1a -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
|
|
.Dl tar --block-compress --gzip --verbose --file /dev/rfd1a --block-size 20 tar/
|
|
.Pp
|
|
The above-created diskette can be listed with
|
|
.Dl tar tvfbz /dev/rfd1a 36
|
|
.Pp
|
|
To join two tar archives into a single archive, use
|
|
.Dl 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
|
|
.Dl cat archive2.tar >> archive1.tar
|
|
because of the end-of-file block at the end of a tar archive).
|
|
.Sh ENVIRONMENT
|
|
The tar program examines the following environment variables.
|
|
.Bl -tag -width "POSIXLY-CORRECT"
|
|
.It 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.
|
|
.It 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.
|
|
.It TAPE
|
|
Changes tar's default tape drive (which is still overridden by the
|
|
.Fl f
|
|
flag).
|
|
.El
|
|
.Sh FILES
|
|
.Bl -tag -width "/dev/rst0"
|
|
.It Pa /dev/rst0
|
|
The default tape drive.
|
|
.El
|
|
.\" This next request is for sections 1, 6, 7 & 8 only
|
|
.\" (command return values (to shell) and fprintf/stderr type diagnostics)
|
|
.\" .Sh DIAGNOSTICS
|
|
.Sh SEE ALSO
|
|
.Xr compress 1 ,
|
|
.Xr gzip 1 ,
|
|
.Xr pax 1 ,
|
|
.Xr ft 8 ,
|
|
.Xr rmt 8
|
|
.\" .Sh STANDARDS
|
|
.Sh HISTORY
|
|
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.
|
|
.Sh AUTHORS
|
|
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.
|
|
.Sh BUGS
|
|
The
|
|
.Fl C
|
|
feature does not work like historical tar programs, and is probably
|
|
untrustworthy.
|
|
.Pp
|
|
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.
|