Finally add a freakin' man page for tar!
Submitted by: John F. Woods <jfw@jfwhome.funhouse.com> Obtained from: NetBSD
This commit is contained in:
jkh
parent
3b410c524f
commit
87dbeba47b
379
gnu/usr.bin/tar/tar.1
Normal file
379
gnu/usr.bin/tar/tar.1
Normal file
@ -0,0 +1,379 @@
|
||||
.\" 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$
|
||||
.\"
|
||||
.Dd 6 August 1994
|
||||
.Os NetBSD
|
||||
.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 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 readsinto 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.
|
||||
.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 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 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 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.
|
||||
.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.
|
||||
Loading…
x
Reference in New Issue
Block a user