NetBSD/gnu/usr.bin/tar/tar.1

.\" Copyright (c) 1991, 1992, 1993 Free Software Foundation	-*- nroff -*-
.\" See section COPYING for conditions for redistribution
.\"
.\"	Written by John F. Woods <jfw@jfwhome.funhouse.com>
.\"
.\"	$NetBSD: tar.1,v 1.16 1999/09/26 21:29:31 jdolecek Exp $
.\"
.Dd 6 August 1994
.Os
.Dt TAR 1
.Sh NAME
.Nm tar
.Nd tape archiver; manipulate
.Dq 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 preceeded 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 (preceeded 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
.Po default is Pa /dev/rst0 Pc .
If a
.Ar hostname
is specified,
.Nm
will use
.Xr rmt 8
to read or write the specified
.Ar file
on a remote machine. If the given
.Ar file
is
.Ql - ,
then
.Nm
uses stdin or 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 `/'s 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
.Fl -create .
.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 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
.Do decompress Dc Ns ).
.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
.Pa /dev/rst0
with a block size of 20
blocks, containing files named
.Pa bert
and
.Pa 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
.Pa /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
.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 copy a file hierarchy while preserving metadata, type
.\" "-C destdir" and "36 tar/" are hack to prevent not to pass
.\" more than 10 argument to .Dl
.Dl tar cf - -C srcdir ". |" tar xpf "-C destdir"
.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 --create --verbose --file /dev/rfd1a --block-size "36 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
.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 tar archive).
.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 flag 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 the 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 cpio 1 ,
.Xr symlink 7 ,
.Xr rmt 8
.\" .Sh STANDARDS
.Sh HISTORY
The tar format has a rich history, dating back to
.At v6 .
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.
.Sh BUGS
The
.Fl C
feature does not work like historical tar programs, and is probably
untrustworthy.
.Pp
The
.Fl 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.