Finally add a freakin' man page for tar!

Submitted by:	John F. Woods <jfw@jfwhome.funhouse.com>
Obtained from: NetBSD

1 files changed, 379 insertions, 0 deletions

diff --git a/gnu/usr.bin/tar/tar.1 b/gnu/usr.bin/tar/tar.1
new file mode 100644
index 0000000..77a7a29
--- /dev/null
+++ b/gnu/usr.bin/tar/tar.1
@@ -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.