568 lines
14 KiB
Groff
568 lines
14 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>
|
|
.\" Updated by Robert Eckardt <roberte@mep.ruhr-uni-bochum.de>
|
|
.\"
|
|
.\" $FreeBSD$
|
|
.\"
|
|
.Dd December 23, 2000
|
|
.Os FreeBSD
|
|
.Dt TAR 1
|
|
.Sh NAME
|
|
.Nm tar
|
|
.Nd "tape archiver; manipulate ""tar"" archive files"
|
|
.Sh SYNOPSIS
|
|
.Nm
|
|
.Op Oo Fl Oc Ns Ar bundled-options Ar Args
|
|
.Op Ar gnu-style-flags
|
|
.Op Ar filenames | Fl C Ar directory-name
|
|
.Ar ...
|
|
.Sh DESCRIPTION
|
|
.Nm Tar
|
|
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
|
|
.Nm
|
|
format, called a
|
|
.Ar tarfile .
|
|
A
|
|
.Ar 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
|
|
.Em append ,
|
|
.Em create ,
|
|
.Em difference ,
|
|
.Em replace ,
|
|
.Em table of contents ,
|
|
.Em update ,
|
|
and
|
|
.Em 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
|
|
.Sx 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
|
|
.Nm
|
|
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
|
|
.Ar 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
|
|
.Ar 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
|
|
.Nm .
|
|
.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
|
|
.Ar number
|
|
* 512-byte blocks.
|
|
.It Fl B
|
|
.It Fl -read-full-blocks
|
|
Re-assemble short reads into full blocks (for reading
|
|
.Bx 4.2
|
|
pipes).
|
|
.It Fl C Ar directory
|
|
.It Fl -directory Ar directory
|
|
Change to
|
|
.Ar directory
|
|
before processing the remaining arguments.
|
|
.It Fl -checkpoint
|
|
Print number of buffer reads/writes while reading/writing the archive.
|
|
.It Fl f Xo
|
|
.Oo Ar hostname : Oc Ns Ar file
|
|
.Xc
|
|
.It Fl -file Xo
|
|
.Oo Ar hostname : Oc Ns Ar file
|
|
.Xc
|
|
Read or write the specified
|
|
.Ar file
|
|
(default is
|
|
.Pa /dev/sa0 ) .
|
|
If a
|
|
.Ar hostname
|
|
is specified,
|
|
.Nm
|
|
will use
|
|
.Xr rmt 8
|
|
to read or write the specified
|
|
.Ar file
|
|
on a remote machine.
|
|
.Dq Ar -
|
|
may be used as a filename, for reading
|
|
or writing to/from stdin/stdout.
|
|
.It Fl -force-local
|
|
Archive file is local even if it has a colon.
|
|
.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 j
|
|
.It Fl y
|
|
.It Fl -bzip
|
|
.It Fl -bzip2
|
|
.It Fl -bunzip2
|
|
Filter the archive through
|
|
.Xr bzip2 1 .
|
|
.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
|
|
.Ar number
|
|
* 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
|
|
.It Fl -norecurse
|
|
Don't recurse into subdirectories when creating.
|
|
.It Fl -volno-file Ar file
|
|
File name with volume number to start with.
|
|
.It Fl N Ar date
|
|
.It Fl -after-date Ar date
|
|
.It Fl -newer Ar date
|
|
Only store files with creation time newer than
|
|
.Ar date .
|
|
.It Fl -newer-mtime Ar date
|
|
Only store files with modification time 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
|
|
.Ql /
|
|
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 -show-omitted-dirs
|
|
Show directories which were omitted while processing the archive.
|
|
.It Fl S
|
|
.It Fl -sparse
|
|
Handle
|
|
.Dq sparse
|
|
files efficiently.
|
|
.It Fl T Ar file
|
|
.It Fl I 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
|
|
.Fl -create .
|
|
.It Fl U
|
|
.It Fl -unlink
|
|
.It Fl -unlink-first
|
|
Unlink files before creating them.
|
|
.It Fl v
|
|
.It Fl -verbose
|
|
Lists files written to archive with
|
|
.Fl -create
|
|
or extracted with
|
|
.Fl -extract ;
|
|
lists file protection information along with file names with
|
|
.Fl -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
|
|
.Nm
|
|
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
|
|
.Dq 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 Xo
|
|
.Op Cm 0 Ns - Ns Cm 7 Ns
|
|
.Op Cm lmh
|
|
.Xc
|
|
Specify tape drive and density.
|
|
.El
|
|
.Sh ENVIRONMENT
|
|
The environment variable
|
|
.Ev TAR_OPTIONS
|
|
can hold a set of default options for
|
|
.Nm .
|
|
These options are interpreted first and can be overwritten by explicit command
|
|
line parameters.
|
|
.Sh EXAMPLES
|
|
To create an archive on tape drive
|
|
.Pa /dev/sa0
|
|
with a block size of 20 blocks, containing files named
|
|
.Pa bert
|
|
and
|
|
.Pa ernie ,
|
|
you can enter
|
|
.Dl "tar cfb /dev/sa0 20 bert ernie"
|
|
or
|
|
.Dl "tar --create --file /dev/sa0 --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
|
|
.Pa /dev/sa0
|
|
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
|
|
.Pa 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
|
|
.Xr gzip 1 ,
|
|
use a command-line like
|
|
.Dl "tar --block-compress -z -c -v -f /dev/fd1a -b 36 tar/"
|
|
.Pp
|
|
Note that you cannot mix bundled flags and
|
|
.Fl -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/fd1a --block-size 20 tar/"
|
|
.Pp
|
|
The above-created diskette can be listed with
|
|
.Dl "tar tvfbz /dev/fd1a 36"
|
|
.Pp
|
|
To join two
|
|
.Nm
|
|
archives into a single archive, use
|
|
.Dl "tar Af archive1.tar archive2.tar"
|
|
which will add the files contained in
|
|
.Pa archive2.tar
|
|
onto the end of
|
|
.Pa 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
|
|
.Nm
|
|
archive).
|
|
.Pp
|
|
To archive all files from the directory
|
|
.Pa srcdir ,
|
|
which were modified
|
|
after Feb. 9th 1997, 13:00 h, use
|
|
.Dl "tar -c -f backup.tar --newer-mtime 'Feb 9 13:15 1997' srcdir/"
|
|
.Pp
|
|
Other possible time specifications are
|
|
.Sq "02/09/97 13:15" ,
|
|
.Sq "1997-02-09 13:15" ,
|
|
.Sq "13:15 9 Feb 1997" ,
|
|
.Sq "9 Feb 1997 13:15" ,
|
|
.Sq "Feb. 9, 1997 1:15pm" ,
|
|
.Sq "09-Feb" ,
|
|
.Sq "3 weeks ago"
|
|
or
|
|
.Sq "May first Sunday" .
|
|
To specify the correct time zone use either e.g.\&
|
|
.Sq "13:15 CEST"
|
|
or
|
|
.Sq "13:15+200" .
|
|
.Sh ENVIRONMENT
|
|
The
|
|
.Nm
|
|
program examines the following environment variables.
|
|
.Bl -tag -width "POSIXLY_CORRECT"
|
|
.It Ev POSIXLY_CORRECT
|
|
Normally,
|
|
.Nm
|
|
will process flag arguments that appear in the file list.
|
|
If set in the environment, this causes
|
|
.Nm
|
|
to consider the first
|
|
non-flag argument to terminate flag processing, as per the POSIX specification.
|
|
.It Ev SHELL
|
|
In interactive mode, a permissible response to the prompt is to
|
|
request to spawn a subshell, which will be
|
|
.Pa /bin/sh
|
|
unless the
|
|
.Ev SHELL
|
|
variable is set.
|
|
.It Ev TAPE
|
|
Changes
|
|
.Nm Ns 's
|
|
default tape drive (which is still overridden by the
|
|
.Fl f
|
|
flag).
|
|
.It TAR_RSH
|
|
The TAR_RSH environment variable allows you to override the default
|
|
shell used as the transport for
|
|
.Nm .
|
|
.El
|
|
.Sh FILES
|
|
.Bl -tag -width "/dev/sa0"
|
|
.It Pa /dev/sa0
|
|
The default tape drive.
|
|
.El
|
|
.Sh COMPATIBILITY
|
|
The
|
|
.Fl y
|
|
is a
|
|
.Fx
|
|
localism.
|
|
The GNU
|
|
.Nm
|
|
maintainer has now choosen
|
|
.Fl j
|
|
as the offical
|
|
.Xr bzip2 1
|
|
compression option in GNU
|
|
.Nm
|
|
1.13.18 and later.
|
|
The
|
|
.Fl I
|
|
option is for compatibility with Solaris's
|
|
.Nm .
|
|
.Sh SEE ALSO
|
|
.Xr bzip2 1 ,
|
|
.Xr compress 1 ,
|
|
.Xr gzip 1 ,
|
|
.Xr pax 1 ,
|
|
.Xr rmt 8
|
|
.Sh HISTORY
|
|
The
|
|
.Nm
|
|
format has a rich history, dating back to Sixth Edition
|
|
.Ux .
|
|
The current implementation of
|
|
.Nm
|
|
is the GNU implementation, which
|
|
originated as the public-domain
|
|
.Nm
|
|
written by
|
|
.An John Gilmore .
|
|
.Sh AUTHORS
|
|
.An -nosplit
|
|
A cast of thousands, including [as listed in the
|
|
.Pa ChangeLog
|
|
file in the source]
|
|
.An John Gilmore
|
|
(author of original public domain version),
|
|
.An Jay Fenlason
|
|
(first GNU author),
|
|
.An Joy Kendall ,
|
|
.An Jim Kingdon ,
|
|
.An David J. MacKenzie ,
|
|
.An Michael I Bushnell ,
|
|
.An Noah Friedman ,
|
|
and innumerable others who have contributed fixes and additions.
|
|
.Pp
|
|
Man page obtained by the
|
|
.Fx
|
|
group from the
|
|
.Nx 1.0
|
|
release.
|
|
.Sh BUGS
|
|
The
|
|
.Fl C
|
|
feature does not work like historical
|
|
.Nm
|
|
programs, and is probably untrustworthy.
|
|
.Pp
|
|
The
|
|
.Fl A
|
|
command should work to join an arbitrary number of
|
|
.Nm
|
|
archives
|
|
together, but it does not; attempting to do so leaves the
|
|
end-of-archive blocks in place for the second and subsequent archives.
|