-\input texinfo @c -*-texinfo-*-
-@c %**start of header
+\input texinfo @c -*-texinfo-*-
+@comment %**start of header
@setfilename tar.info
-@settitle The Tar Manual: DRAFT
+@include version.texi
+@settitle GNU tar @value{VERSION}
@setchapternewpage odd
-@c %**end of header
-@c Note: the edition number and date is listed in *two* places; please update.
-@c subtitle and top node; search for !!set
+@finalout
-@c Search for comments marked with !! or <<< (or >>>)
+@smallbook
+@c %**end of header
-@c <<< CONVENTIONS: this manual refers to "ordinary files" , "directory
-files" (or "directories"), "archive files", "archive members", and
-various I/O devices (which have names and file names).>>>
+@include rendition.texi
+@include value.texi
-@c <<< it's "file name" (not filename) unless we are talking about an
-argument, ie. @var{file-name}. also, you "use" a "file-name argument"
-to "specify" a "file".>>>
+@c Put everything in one index (arbitrarily chosen to be the concept index).
+@syncodeindex fn cp
+@syncodeindex ky cp
+@syncodeindex pg cp
+@syncodeindex vr cp
-@c <<< @code{tar} is always lower case, in bold. >>>
+@defindex op
-@c <<< it's "operations of tar", "options to tar" also, it's " @samp{tar
-+foo}" or "the @samp{+foo} operation". MIB doesn't like using
-operations and options as separate concepts. I disagree --- would be a
-mess to explain otherwise
+@copying
-@c <<< (don't forget to comment these out in final draft) -ringo
+This manual is for @acronym{GNU} @command{tar} (version
+@value{VERSION}, @value{UPDATED}), which creates and extracts files
+from archives.
-@c <<< please dont' change this without sending me e-mail. some things
-@c are in progress or waiting to be edited in hardcopy. -ringo
-@c smallbook
+Copyright @copyright{} 1992, 1994, 1995, 1996, 1997, 1999, 2000, 2001,
+2003, 2004, 2005, 2006 Free Software Foundation, Inc.
-@iftex
-@c finalout
-@end iftex
+@quotation
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.1 or
+any later version published by the Free Software Foundation; with the
+Invariant Sections being "GNU General Public License", with the
+Front-Cover Texts being ``A GNU Manual,'' and with the Back-Cover Texts
+as in (a) below. A copy of the license is included in the section
+entitled "GNU Free Documentation License".
+
+(a) The FSF's Back-Cover Text is: ``You are free to copy and modify
+this GNU Manual. Buying copies from GNU Press supports the FSF in
+developing GNU and promoting software freedom.''
+@end quotation
+@end copying
-@ifinfo
-This file documents @code{tar}, a utility used to store, backup, and
-transport files.
+@dircategory Archiving
+@direntry
+* Tar: (tar). Making tape (or disk) archives.
+@end direntry
-Copyright (C) 1992 Free Software Foundation, Inc. DRAFT!
-@c Need to put distribution information here when ready.
-@end ifinfo
+@dircategory Individual utilities
+@direntry
+* tar: (tar)tar invocation. Invoking @GNUTAR{}.
+@end direntry
+
+@shorttitlepage @acronym{GNU} @command{tar}
-@c !!set edition number and date here
@titlepage
-@title @code{tar}
-@subtitle The GNU Tape Archiver
-@subtitle Edition 0.01, for @code{tar} Version 1.10
-@subtitle @today{}
-@c remove preceding today line when ready
-@sp 1
-@subtitle DRAFT
-@c subtitle insert month here when ready
-
-@author Amy Gorin and Jay Fenlason
-@c <<<best to have hack read this over and see if anything is left he
-@c wrote. I don't think so. -ringo>>>>
+@title @acronym{GNU} tar: an archiver tool
+@subtitle @value{RENDITION} @value{VERSION}, @value{UPDATED}
+@author John Gilmore, Jay Fenlason et al.
@page
@vskip 0pt plus 1filll
-Copyright @copyright{} 1992 Free Software Foundation, Inc.
-
-@sp 2
-This draft is not yet ready for distribution.
+@insertcopying
@end titlepage
-@ifinfo
-@node Top, Introduction, (dir), (dir)
-@top @code{tar}
-
-This file documents @code{tar}, a utility used to store, backup, and
-transport files.
+@ifnottex
+@node Top
+@top @acronym{GNU} tar: an archiver tool
-@c !!set edition number and date here
-This is DRAFT Edition 0.01 of the @code{tar} documentation, @today{}, for @code{tar}
-version 1.12.
-@end ifinfo
-
-@c <<< The menus need to be gone over, and node names fixed.
-@menu
-* Introduction:: @code{tar}: The GNU Tape Archiver
-* Invoking @code{tar}:: How to invoke @code{tar}
-* Tutorial:: Getting started
-* Wizardry:: Some More Advanced Uses for @code{tar}
-* Archive Structure:: The structure of an archive
-* Reading and Writing:: Reading and writing archives
-* Insuring Accuracy:: How to insure the accuracy of an archive
-* Selecting Archive Members:: How to select archive members
-* User Interaction:: How @code{tar} interacts with people.
-* Backups and Restoration:: How to restore files and perform backups
-* Media:: Using tapes and other archive media
-* Quick Reference:: A quick reference guide to
- @code{tar} operations and options
-* Data Format Details:: Details of the archive data format
-* Concept Index:: Concept Index
-@end menu
+@insertcopying
-@node Introduction, Invoking @code{tar}, Top, Top
-@chapter @code{tar}: The GNU Tape Archiver
+@cindex file archival
+@cindex archiving files
-You can use @code{tar} to create an @dfn{archive}---a single file
-which contains other file's contents as well as a listing of those
-files' characteristics. You can also use @code{tar} to read, add to,
-or manipulate already existing archives. Because an archive created
-by @code{tar} is capable of preserving file information and directory
-structure, @code{tar} is ideal for performing full and incremental
-backups, as well as for transferring groups of files between disks and
-over networks.
+The first part of this master menu lists the major nodes in this Info
+document. The rest of the menu lists all the lower level nodes.
+@end ifnottex
-Despite the utility's name, which comes from the words @samp{T(ape)}
-@samp{AR(chiver)}, @code{tar}'s output can be directed to any
-available device. For instance, @code{tar} archives can be stored in
-a file or sent to another program via a pipe.
+@c The master menu, created with texinfo-master-menu, goes here.
+@c (However, getdate.texi's menu is interpolated by hand.)
-@c <<< this menu will conflict with menu above in info mode. -ringo
@menu
-* Invoking @code{tar}:: How to invoke @code{tar} and specify arguments.
-* Tutorial:: An introduction to @code{tar}.
-* Operations:: What you can use @code{tar} to do.
-* Options:: How to change the way @code{tar} behaves.
-* Problems:: Common problems with @code{tar}.
-@end menu
+* Introduction::
+* Tutorial::
+* tar invocation::
+* operations::
+* Backups::
+* Choosing::
+* Date input formats::
+* Formats::
+* Media::
+
+Appendices
+
+* Changes::
+* Configuring Help Summary::
+* Genfile::
+* Snapshot Files::
+* Free Software Needs Free Documentation::
+* Copying This Manual::
+* Index of Command Line Options::
+* Index::
+
+@detailmenu
+ --- The Detailed Node Listing ---
-@node Invoking @code{tar}, Tutorial, Introduction, Top
-@chapter How To Invoke @code{tar}
+Introduction
-You can use @code{tar} to store files in an archive, to extract them
-from an archive, and to do other types of archive manipulation. The
-primary argument to @code{tar}, which is called the @dfn{operation},
-specifies which action to take. The other arguments to @code{tar} are
-either @dfn{options}, which change the way @code{tar} performs an
-operation, or @dfn{file-names}, which specify the files @code{tar} is
-to act on. The typical @code{tar} command line syntax is:
+* Book Contents:: What this Book Contains
+* Definitions:: Some Definitions
+* What tar Does:: What @command{tar} Does
+* Naming tar Archives:: How @command{tar} Archives are Named
+* Authors:: @GNUTAR{} Authors
+* Reports:: Reporting bugs or suggestions
-@example
-@code{tar} @var{operation} [@var{options}...] [@var{file-names}...]
-@end example
+Tutorial Introduction to @command{tar}
-Note: You can actually type in arguments in any order. In this manual
-the operation is always first, the options second and the file-name
-arguments last, to make examples easier to understand.
+* assumptions::
+* stylistic conventions::
+* basic tar options:: Basic @command{tar} Operations and Options
+* frequent operations::
+* Two Frequent Options::
+* create:: How to Create Archives
+* list:: How to List Archives
+* extract:: How to Extract Members from an Archive
+* going further::
-@menu
-* Argument Functions:: The Functions of Arguments
-* Argument Form:: The Forms of Arguments
-* Old Syntax for Commands:: An Old, but Still Supported, Syntax
- for @code{tar} Commands
-@end menu
+Two Frequently Used Options
-@node Argument Functions, Argument Form, Invoking @code{tar}, Invoking @code{tar}
-@section The Functions of Arguments
+* file tutorial::
+* verbose tutorial::
+* help tutorial::
-The primary argument to @code{tar} is the @dfn{operation}, which
-specifies what @code{tar} does. @code{tar} can be used to:
+How to Create Archives
-@itemize
-@item
-Add files to an existing archive (@samp{+add-file}, @samp+{append} or
-@samp{-r})
+* prepare for examples::
+* Creating the archive::
+* create verbose::
+* short create::
+* create dir::
-@item
-Compare files in an archive with files in the file system
-(@samp{+compare}, @samp{+diff} or @samp{-d})
-@c !!! is diff still working?? --- yes -ringo
+How to List Archives
-@item
-Add archives to another archive (@samp{+add-archive}, @samp{+catenate}
-or @samp{-A})
-@c was +concatenate. -ringo
+* list dir::
-@item
-Create an archive (@samp{+create} or @samp{-c})
+How to Extract Members from an Archive
-@item
-Delete files from an archive (@samp{+delete})
-@c -D should have been removed -ringo
+* extracting archives::
+* extracting files::
+* extract dir::
+* failing commands::
-@item
-Extract files from an archive (@samp{+extract}, @samp{+get} or @samp{-x})
+Invoking @GNUTAR{}
-@item
-List the files in an archive (@samp{+list} or @samp{-t})
+* Synopsis::
+* using tar options::
+* Styles::
+* All Options::
+* help::
+* defaults::
+* verbose::
+* interactive::
-@item
-Update an archive by appending newer versions of already stored files
-(@samp{+update} or @samp{-u})
-@end itemize
+The Three Option Styles
-@xref{Reading and Writing}, for more information about these
-operations.
-
-@dfn{Option} arguments to @code{tar} change details of the operation,
-such as archive format, archive name, or level of user interaction.
-You can specify more than one option. All options are optional.
-
-@dfn{File-name} arguments specify which files (including directory
-files) to archive, extract, delete or otherwise operate on.
-
-If you don't use any file-name arguments, @samp{+add-file},
-@samp{+update} and @samp{+delete} will do nothing. The other
-operations of @code{tar} will act on defaults.
-
-When you use a file-name argument to specify a directory file,
-@code{tar} acts on all the files in that directory, including
-sub-directories.
-
-@node Argument Form, Old Syntax for Commands, Argument Functions, Invoking @code{tar}
-@section The Forms of Arguments
-
-Most operations of @code{tar} have a single letter form (a single
-letter preceded by a @samp{-}), and at least one mnemonic form (a
-word or abbreviation preceded by a @samp{+}). The forms are
-identical in function. For example, you can use either @samp{tar -t}
-or @samp{tar +list} to list the contents of an archive
-
-Options, like operations, have both single letter and mnemonic forms.
-Options, however, may also incorporate an argument. Single letter
-options are separated from their arguments by a space. Mnemonic
-options are separated from their arguments by an @samp{=} sign. For
-example, to create an an archive file named @file{george}, use either
-@samp{tar +create +file=george} or @samp{tar +create -f george}. Both
-@samp{+file=@var{archive-name}} and @samp{-f @var{archive-name}}
-denote the option to give the archive a non-default name, which in the
-example is @samp{george}.
-
-You can mix single letter and mnemonic forms in the same command. You
-could type the above example as @samp{tar -c +file=george} or
-@samp{tar +create -f george}. However, @code{tar} operations and
-options are case sensitive. You would not type the above example as
-@samp{tar -C +file=george}, because @samp{-C} is an option that causes
-@code{tar} to change directories, not an operation that creates an
-archive.
+* Mnemonic Options:: Mnemonic Option Style
+* Short Options:: Short Option Style
+* Old Options:: Old Option Style
+* Mixing:: Mixing Option Styles
-File-name arguments are the names of files (including directories).
-These names can be specified on the command line or read from a text
-file in the file system (using the @samp{+files-from} option). Files
-stored in an archive are called @dfn{archive members}. The operations
-@samp{+delete}, @samp{+extract}, @samp{+list}, @samp{+compare} and
-@samp{+update} take the names of archive members as file-name
-arguments. The other operations take the names of files in the file
-system.
+All @command{tar} Options
-@code{tar} interprets relative file names as being relative to the
-working directory. @code{tar} will make all file names relative (by
-removing leading @samp{/}s when archiving or restoring files), unless
-you specify otherwise (using the @samp{+absolute-paths} option).
-@xref{File Name Interpretation}, for more information about
-@samp{+absolute-paths}.
-@c >>> yet another node name that is probably wrong.
+* Operation Summary::
+* Option Summary::
+* Short Option Summary::
-@node Old Syntax for Commands, , Argument Form, Invoking @code{tar}
-@section An Old, but Still Supported, Syntax for @code{tar} Commands
+@GNUTAR{} Operations
-For historical reasons, GNU @code{tar} also accepts a syntax for
-commands which splits options that include arguments into two parts.
-That syntax is of the form:
+* Basic tar::
+* Advanced tar::
+* create options::
+* extract options::
+* backup::
+* Applications::
+* looking ahead::
-@example
-@code{tar} @var{operation}[@var{option-letters}...] [@var{option-arguments}...] [@var{file-names}...]@refill
-@end example
+Advanced @GNUTAR{} Operations
-@noindent
-where arguments to the options appear in the same order as the letters
-to which they correspond, and the operation and all the option letters
-appear as a single argument, without separating spaces.
+* Operations::
+* append::
+* update::
+* concatenate::
+* delete::
+* compare::
-This command syntax is useful because it lets you type the single
-letter forms of the operation and options as a single argument to
-@code{tar}, without writing preceding @samp{-}s or inserting spaces
-between letters. @samp{tar cv} or @samp{tar -cv} are equivalent to
-@samp{tar -c -v}.
+How to Add Files to Existing Archives: @option{--append}
-This old style syntax makes it difficult to match option letters with
-their corresponding arguments, and is often confusing. In the command
-@samp{tar cvbf 20 /dev/rmt0}, for example, @samp{20} is the argument
-for @samp{-b}, @samp{/dev/rmt0} is the argument for @samp{-f}, and
-@samp{-v} does not have a corresponding argument. The modern
-syntax---@samp{tar -c -v -b 20 -f /dev/rmt0}---is clearer.
+* appending files:: Appending Files to an Archive
+* multiple::
-@node Tutorial, Wizardry, Invoking @code{tar}, Top
-@chapter Getting Started With @code{tar}
+Updating an Archive
-This chapter guides you through some basic examples of @code{tar}
-operations. In the examples, the lines you should type are preceded
-by a @samp{%}, which is a typical shell prompt. We use mnemonic forms
-of operations and options in the examples, and in discussions in the
-text, but short forms produce the same result.
+* how to update::
-@menu
-* Creating Archives:: Creating Archives
-* Extracting Files:: Extracting Files from an Archive
-* Listing Archive Contents:: Listing the Contents of an Archive
-* Comparing Files:: Comparing Archives with the File System
-* Adding to Archives:: Adding Files to Existing Archives
-* Concatenate:: Concatenating Archives
-* Deleting Files:: Deleting Files From an Archive
-@end menu
+Options Used by @option{--create}
-@node Creating Archives, Listing Archive Contents, Tutorial, Tutorial
-@section Creating Archives
+* Ignore Failed Read::
-To create a new archive, use @code{tar +create} (or @code{tar -c}).
-You can use options to specify the name and format of the archive (as
-well as other characteristics), and you can use file-name arguments to
-specify which files to put in the archive. If you don't use any
-options or file-name arguments, @code{tar} will use default values.
-@xref{Creating Example}, for more information about the @samp{+create}
-operation.
+Options Used by @option{--extract}
-@menu
-* Creating Example:: Creating Archives of Files
-* Subdirectory:: Creating an Archive of a Subdirectory
-@end menu
+* Reading:: Options to Help Read Archives
+* Writing:: Changing How @command{tar} Writes Files
+* Scarce:: Coping with Scarce Resources
-@node Creating Example, Subdirectory, Creating Archives, Creating Archives
-@subsection Creating Archives of Files
+Options to Help Read Archives
-This example shows you how to create an archive file in the working
-directory containing other files in the working directory. The three
-files you archive in this example are called @file{blues},
-@file{folk}, and @file{jazz}. The archive file is called
-@file{records}. While the archive in this example is written to the
-file system, it could also be written to any other device.
+* read full records::
+* Ignore Zeros::
-(If you want to follow along with this and future examples, create a
-directory called @file{practice} containing files called @file{blues},
-@file{folk} and @file{jazz}. To create the directory, type
-@samp{mkdir practice} at the system prompt. It will probably be
-easiest to create the files using a text editor, such as Emacs.)
+Changing How @command{tar} Writes Files
-First, change into the directory containing the files you want to
-archive:
+* Dealing with Old Files::
+* Overwrite Old Files::
+* Keep Old Files::
+* Keep Newer Files::
+* Unlink First::
+* Recursive Unlink::
+* Data Modification Times::
+* Setting Access Permissions::
+* Writing to Standard Output::
+* remove files::
-@example
-% cd practice
-@end example
+Coping with Scarce Resources
-@noindent
-@file{~/practice} is now your working directory.
+* Starting File::
+* Same Order::
-Then, check that the files to be archived do in fact exist in the
-working directory, and make sure there isn't already a file in the
-working directory with the archive name you intend to use. If you
-specify an archive file name that is already in use, @code{tar} will
-overwrite the old file and its contents will be lost.
+Performing Backups and Restoring Files
-To list the names of files in the working directory, type:
+* Full Dumps:: Using @command{tar} to Perform Full Dumps
+* Incremental Dumps:: Using @command{tar} to Perform Incremental Dumps
+* Backup Levels:: Levels of Backups
+* Backup Parameters:: Setting Parameters for Backups and Restoration
+* Scripted Backups:: Using the Backup Scripts
+* Scripted Restoration:: Using the Restore Script
-@example
-% ls
-@end example
+Setting Parameters for Backups and Restoration
-The system responds:
+* General-Purpose Variables::
+* Magnetic Tape Control::
+* User Hooks::
+* backup-specs example:: An Example Text of @file{Backup-specs}
-@example
-blues folk jazz
-%
-@end example
+Choosing Files and Names for @command{tar}
-@noindent
-Then,
-@itemize @bullet
-@item
-Create a new archive (@samp{tar -c} or @samp{tar +create})
+* file:: Choosing the Archive's Name
+* Selecting Archive Members::
+* files:: Reading Names from a File
+* exclude:: Excluding Some Files
+* Wildcards::
+* after:: Operating Only on New Files
+* recurse:: Descending into Directories
+* one:: Crossing File System Boundaries
-@item
-Explicitly name the archive file being created (@samp{-f
-@var{archive-name}} or @samp{+file=@var{archive-name}}). If you don't
-use this option @code{tar} will write the archive to the default
-storage device, which varies from system to system.
-@c <<< this syntax may change. OK now---check before printing -ringo
+Reading Names from a File
-@code{tar} interprets archive file names relative to the working
-directory. Make sure you have write access to the working directory
-before using @code{tar}.
+* nul::
-@item
-Specify which files to put into the archive (@code{tar} interprets
-file names relative to the working directory). If you don't use any
-@var{file-name} arguments, @code{tar} will archive everything in the
-working directory.
-@end itemize
+Excluding Some Files
-@noindent
-Type:
-@example
-% tar +create +file=records blues folk jazz
-@end example
+* controlling pattern-matching with exclude::
+* problems with exclude::
-@noindent
-If you now list the contents of the working directory (@samp{ls}), you
-will find the archive file listed as well as the files you saw
-previously.
+Crossing File System Boundaries
-@example
-% ls
-blues folk jazz records
-%
-@end example
+* directory:: Changing Directory
+* absolute:: Absolute File Names
-@menu
-* Listing Files:: Listing files in an archive
-* Verbose:: Using @code{tar} in Verbose Mode
-@end menu
+Date input formats
-@node Listing Files, Verbose, Creating Example, Creating Example
-@subsubsection Listing files in an archive
+* General date syntax:: Common rules.
+* Calendar date items:: 19 Dec 1994.
+* Time of day items:: 9:20pm.
+* Time zone items:: @sc{est}, @sc{pdt}, @sc{gmt}, ...
+* Day of week items:: Monday and others.
+* Relative items in date strings:: next tuesday, 2 years ago.
+* Pure numbers in date strings:: 19931219, 1440.
+* Seconds since the Epoch:: @@1078100502.
+* Authors of get_date:: Bellovin, Eggert, Salz, Berets, et al.
-You can list the contents of an archive with another operation of
-@code{tar}---@samp{+list} or @samp{-l}. To list the contents of the
-archive you just created, type:
+Controlling the Archive Format
-@example
-% tar +list +file=records
-@end example
+* Portability:: Making @command{tar} Archives More Portable
+* Compression:: Using Less Space through Compression
+* Attributes:: Handling File Attributes
+* Standard:: The Standard Format
+* Extensions:: @acronym{GNU} Extensions to the Archive Format
+* cpio:: Comparison of @command{tar} and @command{cpio}
-@noindent
-@code{tar} will respond:
+Making @command{tar} Archives More Portable
-@example
-blues folk jazz
-@end example
+* Portable Names:: Portable Names
+* dereference:: Symbolic Links
+* old:: Old V7 Archives
+* posix:: @acronym{POSIX} archives
+* Checksumming:: Checksumming Problems
+* Large or Negative Values:: Large files, negative time stamps, etc.
-@xref{Listing Archive Contents}, for a more detailed tutorial of the
-@samp{+list} operation. @xref{Listing Contents}, for more information
-about the @samp{+list} operation.
+Using Less Space through Compression
-@node Verbose, , Listing Files, Creating Example
-@subsubsection Using @code{tar} in Verbose Mode
+* gzip:: Creating and Reading Compressed Archives
+* sparse:: Archiving Sparse Files
-If you include the @samp{+verbose} or @samp{-v} option on the command
-line, @code{tar} will list the files it is acting on as it is working.
-In verbose mode, the creation example above would appear as:
-@cindex Verbose mode example
-@findex -v (verbose mode example)
+Tapes and Other Archive Media
-@example
-% tar +create +file=records +verbose blues folk jazz
-blues
-folk
-jazz
-@end example
+* Device:: Device selection and switching
+* Remote Tape Server::
+* Common Problems and Solutions::
+* Blocking:: Blocking
+* Many:: Many archives on one tape
+* Using Multiple Tapes:: Using Multiple Tapes
+* label:: Including a Label in the Archive
+* verify::
+* Write Protection::
-@noindent
-The first line is the command typed in by the user. The remaining
-lines are generated by @code{tar}. In the following examples we
-usually use verbose mode, though it is almost never required.
+Blocking
-@node Subdirectory, Changing, Creating Example, Creating Archives
-@subsection Creating an Archive of a Subdirectory
+* Format Variations:: Format Variations
+* Blocking Factor:: The Blocking Factor of an Archive
-You can store a directory in an archive by using the directory name as
-a file-name argument to @code{tar}. When you specify a directory
-file, @code{tar} archives the directory file and all the files it
-contains. The names of the directory and the files it contains are
-stored in the archive relative to the current working directory---when
-the directory is extracted they will be written into the file system
-relative to the working directory at that time.
-@c <<< add an xref to +absolute-paths -ringo
+Many Archives on One Tape
-To archive a directory, first move to its superior directory. If you
-have been following the tutorial, you should type:
+* Tape Positioning:: Tape Positions and Tape Marks
+* mt:: The @command{mt} Utility
-@example
-% cd ..
-%
-@end example
+Using Multiple Tapes
-Once in the superior directory, specify the subdirectory using a
-file-name argument. To store the directory file @file{~/practice} in
-the archive file @file{music}, type:
+* Multi-Volume Archives:: Archives Longer than One Tape or Disk
+* Tape Files:: Tape Files
+* Tarcat:: Concatenate Volumes into a Single Archive
-@example
-% tar +create +verbose +file=music practice
-@end example
+GNU tar internals and development
-@noindent
-@code{tar} should respond:
+* Genfile::
+* Snapshot Files::
-@example
-practice/
-practice/blues
-practice/folk
-practice/jazz
-practice/records
-@end example
+Copying This Manual
-Note that @file{~/practice/records}, another archive file, has
-itself been archived. @code{tar} will accept any file as a file to be
-archived, even an archive file.
+* Free Software Needs Free Documentation::
+* GNU Free Documentation License:: License for copying this manual
-@c >>> symbolic links and changing directories are now in main body, not in
-@c >>> tutorial. -ringo
+@end detailmenu
+@end menu
+
+@node Introduction
+@chapter Introduction
-@node Extracting Files
-@section Extracting Files from an Archive
+@GNUTAR{} creates
+and manipulates @dfn{archives} which are actually collections of
+many other files; the program provides users with an organized and
+systematic method for controlling a large amount of data.
+The name ``tar'' originally came from the phrase ``Tape ARchive'', but
+archives need not (and these days, typically do not) reside on tapes.
-Creating an archive is only half the job---there would be no point in
-storing files in an archive if you couldn't retrieve them. To extract
-files from an archive, use the @samp{+extract} or @samp{-x} operation.
+@menu
+* Book Contents:: What this Book Contains
+* Definitions:: Some Definitions
+* What tar Does:: What @command{tar} Does
+* Naming tar Archives:: How @command{tar} Archives are Named
+* Authors:: @GNUTAR{} Authors
+* Reports:: Reporting bugs or suggestions
+@end menu
-To extract specific files, use their names as file-name arguments. If
-you use a directory name as a file-name argument, @code{tar} extracts
-all the files (including subdirectories) in that directory. If you
-don't use any file-name arguments, @code{tar} extracts all the files
-in the archive.
+@node Book Contents
+@section What this Book Contains
+
+The first part of this chapter introduces you to various terms that will
+recur throughout the book. It also tells you who has worked on @GNUTAR{}
+and its documentation, and where you should send bug reports
+or comments.
+
+The second chapter is a tutorial (@pxref{Tutorial}) which provides a
+gentle introduction for people who are new to using @command{tar}. It is
+meant to be self contained, not requiring any reading from subsequent
+chapters to make sense. It moves from topic to topic in a logical,
+progressive order, building on information already explained.
+
+Although the tutorial is paced and structured to allow beginners to
+learn how to use @command{tar}, it is not intended solely for beginners.
+The tutorial explains how to use the three most frequently used
+operations (@samp{create}, @samp{list}, and @samp{extract}) as well as
+two frequently used options (@samp{file} and @samp{verbose}). The other
+chapters do not refer to the tutorial frequently; however, if a section
+discusses something which is a complex variant of a basic concept, there
+may be a cross reference to that basic concept. (The entire book,
+including the tutorial, assumes that the reader understands some basic
+concepts of using a Unix-type operating system; @pxref{Tutorial}.)
+
+The third chapter presents the remaining five operations, and
+information about using @command{tar} options and option syntax.
+
+@FIXME{this sounds more like a @acronym{GNU} Project Manuals Concept [tm] more
+than the reality. should think about whether this makes sense to say
+here, or not.} The other chapters are meant to be used as a
+reference. Each chapter presents everything that needs to be said
+about a specific topic.
+
+One of the chapters (@pxref{Date input formats}) exists in its
+entirety in other @acronym{GNU} manuals, and is mostly self-contained.
+In addition, one section of this manual (@pxref{Standard}) contains a
+big quote which is taken directly from @command{tar} sources.
+
+In general, we give both long and short (abbreviated) option names
+at least once in each section where the relevant option is covered, so
+that novice readers will become familiar with both styles. (A few
+options have no short versions, and the relevant sections will
+indicate this.)
+
+@node Definitions
+@section Some Definitions
+
+@cindex archive
+@cindex tar archive
+The @command{tar} program is used to create and manipulate @command{tar}
+archives. An @dfn{archive} is a single file which contains the contents
+of many files, while still identifying the names of the files, their
+owner(s), and so forth. (In addition, archives record access
+permissions, user and group, size in bytes, and data modification time.
+Some archives also record the file names in each archived directory, as
+well as other file and directory information.) You can use @command{tar}
+to @dfn{create} a new archive in a specified directory.
+
+@cindex member
+@cindex archive member
+@cindex file name
+@cindex member name
+The files inside an archive are called @dfn{members}. Within this
+manual, we use the term @dfn{file} to refer only to files accessible in
+the normal ways (by @command{ls}, @command{cat}, and so forth), and the term
+@dfn{member} to refer only to the members of an archive. Similarly, a
+@dfn{file name} is the name of a file, as it resides in the file system,
+and a @dfn{member name} is the name of an archive member within the
+archive.
-Note: @code{tar} will extract an archive member into the file system
-without checking to see if there is already a file with the archive
-member's file name. If there is a file with that name, @code{tar}
-will @strong{overwrite} that file and its contents will be lost.
-@c <<<xref keep-old -ringo
+@cindex extraction
+@cindex unpacking
+The term @dfn{extraction} refers to the process of copying an archive
+member (or multiple members) into a file in the file system. Extracting
+all the members of an archive is often called @dfn{extracting the
+archive}. The term @dfn{unpack} can also be used to refer to the
+extraction of many or all the members of an archive. Extracting an
+archive does not destroy the archive's structure, just as creating an
+archive does not destroy the copies of the files that exist outside of
+the archive. You may also @dfn{list} the members in a given archive
+(this is often thought of as ``printing'' them to the standard output,
+or the command line), or @dfn{append} members to a pre-existing archive.
+All of these operations can be performed using @command{tar}.
+
+@node What tar Does
+@section What @command{tar} Does
+
+@cindex tar
+The @command{tar} program provides the ability to create @command{tar}
+archives, as well as various other kinds of manipulation. For example,
+you can use @command{tar} on previously created archives to extract files,
+to store additional files, or to update or list files which were already
+stored.
+
+Initially, @command{tar} archives were used to store files conveniently on
+magnetic tape. The name @command{tar} comes from this use; it stands for
+@code{t}ape @code{ar}chiver. Despite the utility's name, @command{tar} can
+direct its output to available devices, files, or other programs (using
+pipes). @command{tar} may even access remote devices or files (as archives).
+
+@FIXME{the following table entries need a bit of work..}
+
+You can use @command{tar} archives in many ways. We want to stress a few
+of them: storage, backup, and transportation.
+
+@table @asis
+@item Storage
+Often, @command{tar} archives are used to store related files for
+convenient file transfer over a network. For example, the
+@acronym{GNU} Project distributes its software bundled into
+@command{tar} archives, so that all the files relating to a particular
+program (or set of related programs) can be transferred as a single
+unit.
+
+A magnetic tape can store several files in sequence. However, the tape
+has no names for these files; it only knows their relative position on
+the tape. One way to store several files on one tape and retain their
+names is by creating a @command{tar} archive. Even when the basic transfer
+mechanism can keep track of names, as FTP can, the nuisance of handling
+multiple files, directories, and multiple links makes @command{tar}
+archives useful.
+
+Archive files are also used for long-term storage. You can think of
+this as transportation from the present into the future. (It is a
+science-fiction idiom that you can move through time as well as in
+space; the idea here is that @command{tar} can be used to move archives in
+all dimensions, even time!)
+
+@item Backup
+Because the archive created by @command{tar} is capable of preserving
+file information and directory structure, @command{tar} is commonly
+used for performing full and incremental backups of disks. A backup
+puts a collection of files (possibly pertaining to many users and
+projects) together on a disk or a tape. This guards against
+accidental destruction of the information in those files.
+@GNUTAR{} has special features that allow it to be
+used to make incremental and full dumps of all the files in a
+file system.
+
+@item Transportation
+You can create an archive on one system, transfer it to another system,
+and extract the contents there. This allows you to transport a group of
+files from one system to another.
+@end table
-@node Extracting Specific Files, , ,
-@subsection Extracting Specific Files
+@node Naming tar Archives
+@section How @command{tar} Archives are Named
+
+Conventionally, @command{tar} archives are given names ending with
+@samp{.tar}. This is not necessary for @command{tar} to operate properly,
+but this manual follows that convention in order to accustom readers to
+it and to make examples more clear.
+
+@cindex tar file
+@cindex entry
+@cindex tar entry
+Often, people refer to @command{tar} archives as ``@command{tar} files,'' and
+archive members as ``files'' or ``entries''. For people familiar with
+the operation of @command{tar}, this causes no difficulty. However, in
+this manual, we consistently refer to ``archives'' and ``archive
+members'' to make learning to use @command{tar} easier for novice users.
+
+@node Authors
+@section @GNUTAR{} Authors
+
+@GNUTAR{} was originally written by John Gilmore,
+and modified by many people. The @acronym{GNU} enhancements were
+written by Jay Fenlason, then Joy Kendall, and the whole package has
+been further maintained by Thomas Bushnell, n/BSG, Fran@,{c}ois
+Pinard, Paul Eggert, and finally Sergey Poznyakoff with the help of
+numerous and kind users.
+
+We wish to stress that @command{tar} is a collective work, and owes much to
+all those people who reported problems, offered solutions and other
+insights, or shared their thoughts and suggestions. An impressive, yet
+partial list of those contributors can be found in the @file{THANKS}
+file from the @GNUTAR{} distribution.
+
+@FIXME{i want all of these names mentioned, Absolutely. BUT, i'm not
+sure i want to spell out the history in this detail, at least not for
+the printed book. i'm just not sure it needs to be said this way.
+i'll think about it.}
+
+@FIXME{History is more important, and surely more interesting, than
+actual names. Quoting names without history would be meaningless. FP}
+
+Jay Fenlason put together a draft of a @GNUTAR{}
+manual, borrowing notes from the original man page from John Gilmore.
+This was withdrawn in version 1.11. Thomas Bushnell, n/BSG and Amy
+Gorin worked on a tutorial and manual for @GNUTAR{}.
+Fran@,{c}ois Pinard put version 1.11.8 of the manual together by
+taking information from all these sources and merging them. Melissa
+Weisshaus finally edited and redesigned the book to create version
+1.12. @FIXME{update version number as necessary; i'm being
+optimistic!} @FIXME{Someone [maybe karl berry? maybe bob chassell?
+maybe melissa? maybe julie sussman?] needs to properly index the
+thing.}
+
+For version 1.12, Daniel Hagerty contributed a great deal of technical
+consulting. In particular, he is the primary author of @ref{Backups}.
+
+In July, 2003 @GNUTAR{} was put on CVS at savannah.gnu.org
+(see @url{http://savannah.gnu.org/projects/tar}), and
+active development and maintenance work has started
+again. Currently @GNUTAR{} is being maintained by Paul Eggert, Sergey
+Poznyakoff and Jeff Bailey.
+
+Support for @acronym{POSIX} archives was added by Sergey Poznyakoff.
+
+@node Reports
+@section Reporting bugs or suggestions
+
+@cindex bug reports
+@cindex reporting bugs
+If you find problems or have suggestions about this program or manual,
+please report them to @file{bug-tar@@gnu.org}.
+
+When reporting a bug, please be sure to include as much detail as
+possible, in order to reproduce it. @FIXME{Be more specific, I'd
+like to make this node as detailed as 'Bug reporting' node in Emacs
+manual}.
+
+@node Tutorial
+@chapter Tutorial Introduction to @command{tar}
+
+This chapter guides you through some basic examples of three @command{tar}
+operations: @option{--create}, @option{--list}, and @option{--extract}. If
+you already know how to use some other version of @command{tar}, then you
+may not need to read this chapter. This chapter omits most complicated
+details about how @command{tar} works.
-To extract specific files, specify them using file-name arguments.
+@menu
+* assumptions::
+* stylistic conventions::
+* basic tar options:: Basic @command{tar} Operations and Options
+* frequent operations::
+* Two Frequent Options::
+* create:: How to Create Archives
+* list:: How to List Archives
+* extract:: How to Extract Members from an Archive
+* going further::
+@end menu
-In an example above, you created the archive file
-@file{~/practice/records}, which contained the files @file{blues},
-@file{folk} and @file{jazz} in the @file{practice} directory. If, for
-some reason, you were to lose one of those text files (@samp{rm
-~/practice/blues}), you could extract it from the archive file.
+@node assumptions
+@section Assumptions this Tutorial Makes
-First, change into the @file{practice} directory. Then,
+This chapter is paced to allow beginners to learn about @command{tar}
+slowly. At the same time, we will try to cover all the basic aspects of
+these three operations. In order to accomplish both of these tasks, we
+have made certain assumptions about your knowledge before reading this
+manual, and the hardware you will be using:
@itemize @bullet
@item
-Invoke @code{tar} and specify the @samp{+extract} operation
-(@samp{+extract}, @samp{+get} or @samp{-x})
+Before you start to work through this tutorial, you should understand
+what the terms ``archive'' and ``archive member'' mean
+(@pxref{Definitions}). In addition, you should understand something
+about how Unix-type operating systems work, and you should know how to
+use some basic utilities. For example, you should know how to create,
+list, copy, rename, edit, and delete files and directories; how to
+change between directories; and how to figure out where you are in the
+file system. You should have some basic understanding of directory
+structure and how files are named according to which directory they are
+in. You should understand concepts such as standard output and standard
+input, what various definitions of the term ``argument'' mean, and the
+differences between relative and absolute path names. @FIXME{and what
+else?}
@item
-Specify the archive that the files will be extracted from
-(@samp{+file=@var{archive-name}} or @samp{-f @var{archive-name}})
+This manual assumes that you are working from your own home directory
+(unless we state otherwise). In this tutorial, you will create a
+directory to practice @command{tar} commands in. When we show path names,
+we will assume that those paths are relative to your home directory.
+For example, my home directory path is @file{/home/fsf/melissa}. All of
+my examples are in a subdirectory of the directory named by that path
+name; the subdirectory is called @file{practice}.
@item
-Specify the files to extract, using file-name arguments (if you don't
-specify any files, @code{tar} extracts all the archive members)
+In general, we show examples of archives which exist on (or can be
+written to, or worked with from) a directory on a hard disk. In most
+cases, you could write those archives to, or work with them on any other
+device, such as a tape drive. However, some of the later examples in
+the tutorial and next chapter will not work on tape drives.
+Additionally, working with tapes is much more complicated than working
+with hard disks. For these reasons, the tutorial does not cover working
+with tape drives. @xref{Media}, for complete information on using
+@command{tar} archives with tape drives.
+
+@FIXME{this is a cop out. need to add some simple tape drive info.}
@end itemize
-@example
-% tar +extract +file=records blues
-@end example
+@node stylistic conventions
+@section Stylistic Conventions
+
+In the examples, @samp{$} represents a typical shell prompt. It
+precedes lines you should type; to make this more clear, those lines are
+shown in @kbd{this font}, as opposed to lines which represent the
+computer's response; those lines are shown in @code{this font}, or
+sometimes @samp{like this}.
+
+@c When we have lines which are too long to be
+@c displayed in any other way, we will show them like this:
+
+@node basic tar options
+@section Basic @command{tar} Operations and Options
+
+@command{tar} can take a wide variety of arguments which specify and define
+the actions it will have on the particular set of files or the archive.
+The main types of arguments to @command{tar} fall into one of two classes:
+operations, and options.
+
+Some arguments fall into a class called @dfn{operations}; exactly one of
+these is both allowed and required for any instance of using @command{tar};
+you may @emph{not} specify more than one. People sometimes speak of
+@dfn{operating modes}. You are in a particular operating mode when you
+have specified the operation which specifies it; there are eight
+operations in total, and thus there are eight operating modes.
+
+The other arguments fall into the class known as @dfn{options}. You are
+not required to specify any options, and you are allowed to specify more
+than one at a time (depending on the way you are using @command{tar} at
+that time). Some options are used so frequently, and are so useful for
+helping you type commands more carefully that they are effectively
+``required''. We will discuss them in this chapter.
+
+You can write most of the @command{tar} operations and options in any
+of three forms: long (mnemonic) form, short form, and old style. Some
+of the operations and options have no short or ``old'' forms; however,
+the operations and options which we will cover in this tutorial have
+corresponding abbreviations. @FIXME{make sure this is still the case,
+at the end}We will indicate those abbreviations appropriately to get
+you used to seeing them. (Note that the ``old style'' option forms
+exist in @GNUTAR{} for compatibility with Unix
+@command{tar}. In this book we present a full discussion of this way
+of writing options and operations (@pxref{Old Options}), and we discuss
+the other two styles of writing options (@xref{Mnemonic Options}, and
+@pxref{Short Options}).
+
+In the examples and in the text of this tutorial, we usually use the
+long forms of operations and options; but the ``short'' forms produce
+the same result and can make typing long @command{tar} commands easier.
+For example, instead of typing
+
+@smallexample
+@kbd{tar --create --verbose --file=afiles.tar apple angst aspic}
+@end smallexample
-If you list the contents of the directory, you will see that
-@file{blues} is back:
+@noindent
+you can type
+@smallexample
+@kbd{tar -c -v -f afiles.tar apple angst aspic}
+@end smallexample
-@example
-% ls
-folk
-jazz
-records
-blues
-@end example
-
-@node Extracting Directories, , ,
-@subsection Extracting Directories
-
-To extract a directory and all the files it contains, use the
-directory's name as a file-name argument in conjunction with @samp{tar
-+extract}. Remember---@code{tar} stores and extracts file names
-relative to the working directory.
-
-In a previous example you stored the directory @file{~/practice} in
-the archive file @file{~/music}. If you delete the contents of
-@file{practice}, you can restore them using @code{tar}.
-
-First, change into the @file{practice} subdirectory (@samp{cd
-~/practice}). Then, remove all the files in @samp{~/practice}
-(@samp{rm *}). If you list the contents of the directory, you should
-now see that it is empty:
-
-@example
-%ls
-%
-@end example
-
-@noindent Let's try to restore the contents of @file{practice} by extracting
-them from the archive file @file{~/music}:
-
-@example
-tar +extract +file=~/music practice
-@end example
-
-@noindent Now, list the contents of @file{practice} again:
-
-@example
-%ls
-practice
-@end example
-
-What happened to the files? When you created @file{~/music}, your
-working directory was your home directory. When you extracted
-@file{~/music}, your working directory was @file{~/practice}.
-@code{tar} stored the files in @file{practice} relative to your home
-directory, and then extracted them relative to @file{~/practice}. The
-files are now in a new subdirectory, called
-@file{~/practice/practice}.
-
-To restore your files to their old positions, delete the new directory
-and its contents, and then redo the example above with your home
-directory as the working directory:
-
-@example
-% rm ~/practice/practice/*
-% rmdir practice
-% cd ..
-% tar +extract +file=music practice
-@end example
-
-@noindent (@code{tar} will report that it is unable to create the
-directory @file{~/practice} because it already exists. This will not
-effect the extraction of the other archive members.)
-
-@node Listing Archive Contents, Adding to Archives, Creating Archives, Tutorial
-@section Listing the Contents of an Archive
-
-Use @samp{+list} or @samp{-t} to print the names of files stored in an
-archive. If you use file-name arguments with this operation,
-@code{tar} prints the names of the specified files if they are stored
-in the archive. If you use a directory name as a file-name argument,
-@code{tar} also prints the names of all underlying files, including
-sub-directories. If you use no file-name arguments, @code{tar} prints
-the names of all the archive members.
-
-You can use @samp{+list} with the @samp{+verbose} option to print
-archive members' attributes (owner, size, etc.).
+@noindent
+or even
+@smallexample
+@kbd{tar -cvf afiles.tar apple angst aspic}
+@end smallexample
+
+@noindent
+For more information on option syntax, see @ref{Advanced tar}. In
+discussions in the text, when we name an option by its long form, we
+also give the corresponding short option in parentheses.
+
+The term, ``option'', can be confusing at times, since ``operations''
+are often lumped in with the actual, @emph{optional} ``options'' in certain
+general class statements. For example, we just talked about ``short and
+long forms of options and operations''. However, experienced @command{tar}
+users often refer to these by shorthand terms such as, ``short and long
+options''. This term assumes that the ``operations'' are included, also.
+Context will help you determine which definition of ``options'' to use.
+
+Similarly, the term ``command'' can be confusing, as it is often used in
+two different ways. People sometimes refer to @command{tar} ``commands''.
+A @command{tar} @dfn{command} is the entire command line of user input
+which tells @command{tar} what to do --- including the operation, options,
+and any arguments (file names, pipes, other commands, etc). However,
+you will also sometimes hear the term ``the @command{tar} command''. When
+the word ``command'' is used specifically like this, a person is usually
+referring to the @command{tar} @emph{operation}, not the whole line.
+Again, use context to figure out which of the meanings the speaker
+intends.
+
+@node frequent operations
+@section The Three Most Frequently Used Operations
+
+Here are the three most frequently used operations (both short and long
+forms), as well as a brief description of their meanings. The rest of
+this chapter will cover how to use these operations in detail. We will
+present the rest of the operations in the next chapter.
+
+@table @option
+@item --create
+@itemx -c
+Create a new @command{tar} archive.
+@item --list
+@itemx -t
+List the contents of an archive.
+@item --extract
+@itemx -x
+Extract one or more members from an archive.
+@end table
+
+@node Two Frequent Options
+@section Two Frequently Used Options
+
+To understand how to run @command{tar} in the three operating modes listed
+previously, you also need to understand how to use two of the options to
+@command{tar}: @option{--file} (which takes an archive file as an argument)
+and @option{--verbose}. (You are usually not @emph{required} to specify
+either of these options when you run @command{tar}, but they can be very
+useful in making things more clear and helping you avoid errors.)
@menu
-* Listing names:: Listing the names of stored files
-* Additional File Info:: Getting Additional File Information
-* Specific File:: List A Specific File in an Archive
-* Listing Directories:: Listing the Contents of a Stored Directory
+* file tutorial::
+* verbose tutorial::
+* help tutorial::
@end menu
-@node Listing names, Additional File Info, Listing Archive Contents, Listing Archive Contents
-@subsection Listing the names of stored files
+@node file tutorial
+@unnumberedsubsec The @option{--file} Option
-To list the names of files stored in an archive, use the @samp{+list}
-operation of @code{tar}.
+@table @option
+@opindex file, tutorial
+@item --file=@var{archive-name}
+@itemx -f @var{archive-name}
+Specify the name of an archive file.
+@end table
-In a previous example, you created the archive @file{~/music}. To
-list the contents of @file{music}, while in your home directory:
+You can specify an argument for the @option{--file=@var{archive-name}} (@option{-f @var{archive-name}}) option whenever you
+use @command{tar}; this option determines the name of the archive file
+that @command{tar} will work on.
+
+@vrindex TAPE
+If you don't specify this argument, then @command{tar} will examine
+the environment variable @env{TAPE}. If it is set, its value will be
+used as the archive name. Otherwise, @command{tar} will use the
+default archive, determined at the compile time. Usually it is
+standard output or some physical tape drive attached to your machine
+(you can verify what the default is by running @kbd{tar
+--show-defaults}, @pxref{defaults}). If there is no tape drive
+attached, or the default is not meaningful, then @command{tar} will
+print an error message. The error message might look roughly like one
+of the following:
+
+@smallexample
+tar: can't open /dev/rmt8 : No such device or address
+tar: can't open /dev/rsmt0 : I/O error
+@end smallexample
-@itemize @bullet
-@item
-List the contents of an archive (@samp{tar -t} or @samp{tar +list})
+@noindent
+To avoid confusion, we recommend that you always specify an archive file
+name by using @option{--file=@var{archive-name}} (@option{-f @var{archive-name}}) when writing your @command{tar} commands.
+For more information on using the @option{--file=@var{archive-name}} (@option{-f @var{archive-name}}) option, see
+@ref{file}.
-@item
-Specify the archive to be listed (@samp{-f @var{archive-name}} or
-@samp{+file=@var{archive-name}}) @refill
-@end itemize
+@node verbose tutorial
+@unnumberedsubsec The @option{--verbose} Option
-Thus:
+@table @option
+@opindex verbose, introduced
+@item --verbose
+@itemx -v
+Show the files being worked on as @command{tar} is running.
+@end table
-@example
-% tar +list +file=music
-practice/
-practice/blues
-practice/folk
-practice/jazz
-practice/records
-@end example
+@option{--verbose} (@option{-v}) shows details about the results of running
+@command{tar}. This can be especially useful when the results might not be
+obvious. For example, if you want to see the progress of @command{tar} as
+it writes files into the archive, you can use the @option{--verbose}
+option. In the beginning, you may find it useful to use
+@option{--verbose} at all times; when you are more accustomed to
+@command{tar}, you will likely want to use it at certain times but not at
+others. We will use @option{--verbose} at times to help make something
+clear, and we will give many examples both using and not using
+@option{--verbose} to show the differences.
+
+Sometimes, a single instance of @option{--verbose} on the command line
+will show a full, @samp{ls} style listing of an archive or files,
+giving sizes, owners, and similar information. @FIXME{Describe the
+exact output format, e.g., how hard links are displayed.}
+Other times, @option{--verbose} will only show files or members that the particular
+operation is operating on at the time. In the latter case, you can
+use @option{--verbose} twice in a command to get a listing such as that
+in the former case. For example, instead of saying
+
+@smallexample
+@kbd{tar -cvf afiles.tar apple angst aspic}
+@end smallexample
-@node Additional File Info, Specific File, Listing names, Listing Archive Contents
-@subsection Listing Additional File Information
+@noindent
+above, you might say
-To get more information when you list the names of files stored in an
-archive, specify the @samp{+verbose} option in conjunction with
-@samp{tar +list}. @code{tar} will print archive member's file
-protection, owner and group ID, size, and date and time of creation.
+@smallexample
+@kbd{tar -cvvf afiles.tar apple angst aspic}
+@end smallexample
-For example:
+@noindent
+This works equally well using short or long forms of options. Using
+long forms, you would simply write out the mnemonic form of the option
+twice, like this:
-@example
-% tar +list +verbose +file=music
-drwxrwxrwx myself/user 0 May 31 21:49 1990 practice/
--rw-rw-rw- myself/user 42 May 21 13:29 1990 practice/blues
--rw-rw-rw- myself/user 62 May 23 10:55 1990 practice/folk
--rw-rw-rw- myself/user 40 May 21 13:30 1990 practice/jazz
--rw-rw-rw- myself/user 10240 May 31 21:49 1990 practice/records
-%
-@end example
-
-Note that when you use @samp{+verbose} with @samp{+list}, @code{tar}
-doesn't print the names of files as they are being acted on, though
-the @samp{+verbose} option will have this effect when used with all
-other operations.
-
-@node Specific File, Comparing Files, Additional File Info, Listing Archive Contents
-@subsection List A Specific File in an Archive
-
-To to see if a particular file is in an archive, use the name of the
-file in question as a file-name argument while specifying the
-@samp{+list} operation. For example, to see whether the file
-@file{folk} is in the archive file @file{music}, do the following:
+@smallexample
+$ @kbd{tar --create --verbose --verbose @dots{}}
+@end smallexample
-@itemize @bullet
-@item
-Invoke @code{tar}, and specify the @samp{+list} operation
-(@samp{+list} or @samp{-t}).
+@noindent
+Note that you must double the hyphens properly each time.
-@item
-Specify the archive file to be acted on (@samp{+file
-@var{archive-name}} or @samp{-f @var{archive-name}}).
+Later in the tutorial, we will give examples using @w{@option{--verbose
+--verbose}}.
-@item
-Specify the files to look for, by typing their names as file-name
-arguments. You have to type the file name as it appears in the
-archive (normally, as it is relative to the relative to the directory
-from which the archive was created). <<< xref absolute-paths -ringo
-@end itemize
+@node help tutorial
+@unnumberedsubsec Getting Help: Using the @option{--help} Option
-Type:
+@table @option
+@opindex help
+@item --help
-@example
-% tar +list +file=music practice/folk
-@end example
+The @option{--help} option to @command{tar} prints out a very brief list of
+all operations and option available for the current version of
+@command{tar} available on your system.
+@end table
-@noindent
-@code{tar} responds:
+@node create
+@section How to Create Archives
+@UNREVISED
+
+@cindex Creation of the archive
+@cindex Archive, creation of
+One of the basic operations of @command{tar} is @option{--create} (@option{-c}), which
+you use to create a @command{tar} archive. We will explain
+@option{--create} first because, in order to learn about the other
+operations, you will find it useful to have an archive available to
+practice on.
+
+To make this easier, in this section you will first create a directory
+containing three files. Then, we will show you how to create an
+@emph{archive} (inside the new directory). Both the directory, and
+the archive are specifically for you to practice on. The rest of this
+chapter and the next chapter will show many examples using this
+directory and the files you will create: some of those files may be
+other directories and other archives.
+
+The three files you will archive in this example are called
+@file{blues}, @file{folk}, and @file{jazz}. The archive is called
+@file{collection.tar}.
+
+This section will proceed slowly, detailing how to use @option{--create}
+in @code{verbose} mode, and showing examples using both short and long
+forms. In the rest of the tutorial, and in the examples in the next
+chapter, we will proceed at a slightly quicker pace. This section
+moves more slowly to allow beginning users to understand how
+@command{tar} works.
-@example
-practice/folk
-@end example
+@menu
+* prepare for examples::
+* Creating the archive::
+* create verbose::
+* short create::
+* create dir::
+@end menu
-@noindent
-If the file were not stored in the archive (for example, the file
-@file{practice/rock}), the example above would look like:
+@node prepare for examples
+@subsection Preparing a Practice Directory for Examples
+
+To follow along with this and future examples, create a new directory
+called @file{practice} containing files called @file{blues}, @file{folk}
+and @file{jazz}. The files can contain any information you like:
+ideally, they should contain information which relates to their names,
+and be of different lengths. Our examples assume that @file{practice}
+is a subdirectory of your home directory.
+
+Now @command{cd} to the directory named @file{practice}; @file{practice}
+is now your @dfn{working directory}. (@emph{Please note}: Although
+the full path name of this directory is
+@file{/@var{homedir}/practice}, in our examples we will refer to
+this directory as @file{practice}; the @var{homedir} is presumed.
+
+In general, you should check that the files to be archived exist where
+you think they do (in the working directory) by running @command{ls}.
+Because you just created the directory and the files and have changed to
+that directory, you probably don't need to do that this time.
+
+It is very important to make sure there isn't already a file in the
+working directory with the archive name you intend to use (in this case,
+@samp{collection.tar}), or that you don't care about its contents.
+Whenever you use @samp{create}, @command{tar} will erase the current
+contents of the file named by @option{--file=@var{archive-name}} (@option{-f @var{archive-name}}) if it exists. @command{tar}
+will not tell you if you are about to overwrite an archive unless you
+specify an option which does this (@pxref{backup}, for the
+information on how to do so). To add files to an existing archive,
+you need to use a different option, such as @option{--append} (@option{-r}); see
+@ref{append} for information on how to do this.
+
+@node Creating the archive
+@subsection Creating the Archive
+
+@opindex create, introduced
+To place the files @file{blues}, @file{folk}, and @file{jazz} into an
+archive named @file{collection.tar}, use the following command:
+
+@smallexample
+$ @kbd{tar --create --file=collection.tar blues folk jazz}
+@end smallexample
+
+The order of the arguments is not very important, @emph{when using long
+option forms}. You could also say:
+
+@smallexample
+$ @kbd{tar blues --create folk --file=collection.tar jazz}
+@end smallexample
-@example
-% tar +list +file=music practice/rock
-tar: practice/rock not found in archive
-@end example
+@noindent
+However, you can see that this order is harder to understand; this is
+why we will list the arguments in the order that makes the commands
+easiest to understand (and we encourage you to do the same when you use
+@command{tar}, to avoid errors).
+
+Note that the part of the command which says,
+@w{@option{--file=collection.tar}} is considered to be @emph{one} argument.
+If you substituted any other string of characters for
+@kbd{collection.tar}, then that string would become the name of the
+archive file you create.
+
+The order of the options becomes more important when you begin to use
+short forms. With short forms, if you type commands in the wrong order
+(even if you type them correctly in all other ways), you may end up with
+results you don't expect. For this reason, it is a good idea to get
+into the habit of typing options in the order that makes inherent sense.
+@xref{short create}, for more information on this.
+
+In this example, you type the command as shown above: @option{--create}
+is the operation which creates the new archive
+(@file{collection.tar}), and @option{--file} is the option which lets
+you give it the name you chose. The files, @file{blues}, @file{folk},
+and @file{jazz}, are now members of the archive, @file{collection.tar}
+(they are @dfn{file name arguments} to the @option{--create} operation).
+@FIXME{xref here to the discussion of file name args?}Now that they are
+in the archive, they are called @emph{archive members}, not files.
+(@pxref{Definitions,members}).
+
+When you create an archive, you @emph{must} specify which files you
+want placed in the archive. If you do not specify any archive
+members, @GNUTAR{} will complain.
+
+If you now list the contents of the working directory (@command{ls}), you will
+find the archive file listed as well as the files you saw previously:
+
+@smallexample
+blues folk jazz collection.tar
+@end smallexample
@noindent
-If you had used @samp{+verbose} mode, the example above would look
-like:
+Creating the archive @samp{collection.tar} did not destroy the copies of
+the files in the directory.
-@example
-% tar +list +file=music practice/folk
--rw-rw-rw- myself/user 62 May 23 10:55 1990 practice/folk
-@end example
+Keep in mind that if you don't indicate an operation, @command{tar} will not
+run and will prompt you for one. If you don't name any files, @command{tar}
+will complain. You must have write access to the working directory,
+or else you will not be able to create an archive in that directory.
-@node Listing Directories, , ,
-@subsection Listing the Contents of a Stored Directory
+@emph{Caution}: Do not attempt to use @option{--create} (@option{-c}) to add files to
+an existing archive; it will delete the archive and write a new one.
+Use @option{--append} (@option{-r}) instead. @xref{append}.
-To get information about the contents of an archived directory, use
-the directory name as a file-name argument in conjunction with
-@samp{+list}. To find out file attributes, include the
-@samp{+verbose} option.
+@node create verbose
+@subsection Running @option{--create} with @option{--verbose}
-For example, to find out about files in the directory @file{practice},
-in the archive file @file{music}, type:
+@opindex create, using with @option{--verbose}
+@opindex verbose, using with @option{--create}
+If you include the @option{--verbose} (@option{-v}) option on the command line,
+@command{tar} will list the files it is acting on as it is working. In
+verbose mode, the @code{create} example above would appear as:
-@example
-% tar +list +file=music practice
-@end example
+@smallexample
+$ @kbd{tar --create --verbose --file=collection.tar blues folk jazz}
+blues
+folk
+jazz
+@end smallexample
-@noindent @code{tar} responds:
+This example is just like the example we showed which did not use
+@option{--verbose}, except that @command{tar} generated the remaining lines
+@iftex
+(note the different font styles).
+@end iftex
+@ifinfo
+.
+@end ifinfo
-@example
-drwxrwxrwx myself/user 0 May 31 21:49 1990 practice/
--rw-rw-rw- myself/user 42 May 21 13:29 1990 practice/blues
--rw-rw-rw- myself/user 62 May 23 10:55 1990 practice/folk
--rw-rw-rw- myself/user 40 May 21 13:30 1990 practice/jazz
--rw-rw-rw- myself/user 10240 May 31 21:49 1990 practice/records
-@end example
+In the rest of the examples in this chapter, we will frequently use
+@code{verbose} mode so we can show actions or @command{tar} responses that
+you would otherwise not see, and which are important for you to
+understand.
-When you use a directory name as a file-name argument, @code{tar} acts
-on all the files (including sub-directories) in that directory.
+@node short create
+@subsection Short Forms with @samp{create}
-@node Comparing Files, , ,
-@section Comparing Files in an Archive with Files in the File System
+As we said before, the @option{--create} (@option{-c}) operation is one of the most
+basic uses of @command{tar}, and you will use it countless times.
+Eventually, you will probably want to use abbreviated (or ``short'')
+forms of options. A full discussion of the three different forms that
+options can take appears in @ref{Styles}; for now, here is what the
+previous example (including the @option{--verbose} (@option{-v}) option) looks like
+using short option forms:
-To compare the attributes of archive members with the attributes of
-their counterparts in the file system, use the @samp{+compare},
-@samp{+diff}, or @samp{-d}) operation. While you could use
-@samp{+list +verbose} to manually compare some file attributes, it is
-simpler to have @code{tar} itself compare file attributes and report
-back on file differences.
-@c <<<"manually"? suggestions? -ringo
+@smallexample
+$ @kbd{tar -cvf collection.tar blues folk jazz}
+blues
+folk
+jazz
+@end smallexample
-The @samp{+compare} operation, as its name implies, compares archive
-members with files of the same name in the file system, and reports
-back differences in file size, mode, owner and modification date.
-@samp{tar +compare} acts only on archive members---it ignores files in
-the file system that are not stored in the archive. If you give
-@samp{tar +compare} a file-name argument that does not correspond to
-the name of an archive member, @code{tar} responds with an error
-message.
+@noindent
+As you can see, the system responds the same no matter whether you use
+long or short option forms.
-To compare archive members in the archive file @file{records} with
-files in the @file{~/practice} directory, first change into the
-@file{practice} directory. Then:
+@FIXME{i don't like how this is worded:} One difference between using
+short and long option forms is that, although the exact placement of
+arguments following options is no more specific when using short forms,
+it is easier to become confused and make a mistake when using short
+forms. For example, suppose you attempted the above example in the
+following way:
-@itemize @bullet
-@item
-Invoke @code{tar} and specify the @samp{+compare} operation.
-(@samp{+compare}, @samp{+diff}, or @samp{-d}).
+@smallexample
+$ @kbd{tar -cfv collection.tar blues folk jazz}
+@end smallexample
-@item
-Specify the archive where the files to be compared are stored
-(@samp{+file=@var{archive-name}} or @samp{-f @var{archive-name}})
+@noindent
+In this case, @command{tar} will make an archive file called @file{v},
+containing the files @file{blues}, @file{folk}, and @file{jazz}, because
+the @samp{v} is the closest ``file name'' to the @option{-f} option, and
+is thus taken to be the chosen archive file name. @command{tar} will try
+to add a file called @file{collection.tar} to the @file{v} archive file;
+if the file @file{collection.tar} did not already exist, @command{tar} will
+report an error indicating that this file does not exist. If the file
+@file{collection.tar} does already exist (e.g., from a previous command
+you may have run), then @command{tar} will add this file to the archive.
+Because the @option{-v} option did not get registered, @command{tar} will not
+run under @samp{verbose} mode, and will not report its progress.
+
+The end result is that you may be quite confused about what happened,
+and possibly overwrite a file. To illustrate this further, we will show
+you how an example we showed previously would look using short forms.
+
+This example,
+
+@smallexample
+$ @kbd{tar blues --create folk --file=collection.tar jazz}
+@end smallexample
-@item
-Specify the archive members to be compared. (In this example you are
-comparing all the archive members in the archive. Since this is the
-default, you don't need to use any file-name arguments).
-@end itemize
+@noindent
+is confusing as it is. When shown using short forms, however, it
+becomes much more so:
-@example
-% tar +compare +file=records
-%
-@end example
+@smallexample
+$ @kbd{tar blues -c folk -f collection.tar jazz}
+@end smallexample
@noindent
-While it looks like nothing has happened, @code{tar} has, in fact,
-done the comparison---and found nothing to report.
+It would be very easy to put the wrong string of characters
+immediately following the @option{-f}, but doing that could sacrifice
+valuable data.
+
+For this reason, we recommend that you pay very careful attention to
+the order of options and placement of file and archive names,
+especially when using short option forms. Not having the option name
+written out mnemonically can affect how well you remember which option
+does what, and therefore where different names have to be placed.
+
+@node create dir
+@subsection Archiving Directories
+
+@cindex Archiving Directories
+@cindex Directories, Archiving
+You can archive a directory by specifying its directory name as a
+file name argument to @command{tar}. The files in the directory will be
+archived relative to the working directory, and the directory will be
+re-created along with its contents when the archive is extracted.
-Use the @samp{+verbose} option to list the names of archive members as
-they are being compared with their counterparts of the same name in
-the file system:
+To archive a directory, first move to its superior directory. If you
+have followed the previous instructions in this tutorial, you should
+type:
-@example
-% tar +compare +verbose +file=records
-blues
-folk
-jazz
-%
-@end example
+@smallexample
+$ @kbd{cd ..}
+$
+@end smallexample
@noindent
-If @code{tar} had had anything to report, it would have done so as it
-was comparing each file.
+This will put you into the directory which contains @file{practice},
+i.e., your home directory. Once in the superior directory, you can
+specify the subdirectory, @file{practice}, as a file name argument. To
+store @file{practice} in the new archive file @file{music.tar}, type:
-If you remove the file @file{jazz} from the file system (@samp{rm
-jazz}), and modify the file @file{blues} (for instance, by adding text
-to it with an editor such as Emacs), the above example would look
-like:
+@smallexample
+$ @kbd{tar --create --verbose --file=music.tar practice}
+@end smallexample
-@example
-% tar +compare +verbose +file=records
-blues
-blues: mod time differs
-blues: size differs
-folk
-jazz
-jazz: does not exist
-%
-@end example
+@noindent
+@command{tar} should output:
-Note again that while @samp{tar +compare} reports the names of archive
-members that do not have counterparts in the file system, @samp{tar
-+compare} ignores files in the file system that do not have
-counterparts in the archive. To demonstrate this, create a file in
-the @file{practice} directory called @file{rock} (using any text
-editor). The new file appears when you list the directory's contents:
+@smallexample
+practice/
+practice/blues
+practice/folk
+practice/jazz
+practice/collection.tar
+@end smallexample
+
+Note that the archive thus created is not in the subdirectory
+@file{practice}, but rather in the current working directory---the
+directory from which @command{tar} was invoked. Before trying to archive a
+directory from its superior directory, you should make sure you have
+write access to the superior directory itself, not only the directory
+you are trying archive with @command{tar}. For example, you will probably
+not be able to store your home directory in an archive by invoking
+@command{tar} from the root directory; @xref{absolute}. (Note
+also that @file{collection.tar}, the original archive file, has itself
+been archived. @command{tar} will accept any file as a file to be
+archived, regardless of its content. When @file{music.tar} is
+extracted, the archive file @file{collection.tar} will be re-written
+into the file system).
+
+If you give @command{tar} a command such as
+
+@smallexample
+$ @kbd{tar --create --file=foo.tar .}
+@end smallexample
-@example
-% ls
-blues folk records rock
-@end example
+@noindent
+@command{tar} will report @samp{tar: ./foo.tar is the archive; not
+dumped}. This happens because @command{tar} creates the archive
+@file{foo.tar} in the current directory before putting any files into
+it. Then, when @command{tar} attempts to add all the files in the
+directory @file{.} to the archive, it notices that the file
+@file{./foo.tar} is the same as the archive @file{foo.tar}, and skips
+it. (It makes no sense to put an archive into itself.) @GNUTAR{}
+will continue in this case, and create the archive
+normally, except for the exclusion of that one file. (@emph{Please
+note:} Other versions of @command{tar} are not so clever; they will
+enter an infinite loop when this happens, so you should not depend on
+this behavior unless you are certain you are running @GNUTAR{}.)
+ @FIXME{bob doesn't like this sentence, since he does
+it all the time, and we've been doing it in the editing passes for
+this manual: In general, make sure that the archive is not inside a
+directory being dumped.}
+
+@node list
+@section How to List Archives
+
+@opindex list
+Frequently, you will find yourself wanting to determine exactly what a
+particular archive contains. You can use the @option{--list} (@option{-t}) operation
+to get the member names as they currently appear in the archive, as well
+as various attributes of the files at the time they were archived. For
+example, you can examine the archive @file{collection.tar} that you
+created in the last section with the command,
+
+@smallexample
+$ @kbd{tar --list --file=collection.tar}
+@end smallexample
@noindent
-If you type the @samp{+compare} example again, @code{tar} prints the
-following:
+The output of @command{tar} would then be:
-@example
-% tar +compare +verbose +file=records
+@smallexample
blues
-blues: mod time differs
-blues: size differs
folk
jazz
-jazz: does not exist
-%
-@end example
+@end smallexample
+
+@FIXME{we hope this will change. if it doesn't, need to show the
+creation of bfiles somewhere above!!! : }
+
+@noindent
+The archive @file{bfiles.tar} would list as follows:
+
+@smallexample
+./birds
+baboon
+./box
+@end smallexample
@noindent
-@code{tar} ignores the file @file{rock} because @code{tar} is
-comparing archive members to files in the file system, not vice versa.
+Be sure to use a @option{--file=@var{archive-name}} (@option{-f @var{archive-name}}) option just as with @option{--create} (@option{-c})
+to specify the name of the archive.
-If you specify @file{rock} explicitly (using a file-name argument),
-@code{tar} prints an error message:
+@opindex list, using with @option{--verbose}
+@opindex verbose, using with @option{--list}
+If you use the @option{--verbose} (@option{-v}) option with @option{--list}, then
+@command{tar} will print out a listing reminiscent of @w{@samp{ls -l}},
+showing owner, file size, and so forth.
-@example
-% tar +compare +verbose +file=records rock
-tar: rock not found in archive
-%
-@end example
+If you had used @option{--verbose} (@option{-v}) mode, the example above would look
+like:
+
+@smallexample
+$ @kbd{tar --list --verbose --file=collection.tar folk}
+-rw-r--r-- myself user 62 1990-05-23 10:55 folk
+@end smallexample
+
+@cindex listing member and file names
+@anchor{listing member and file names}
+It is important to notice that the output of @kbd{tar --list
+--verbose} does not necessarily match that produced by @kbd{tar
+--create --verbose} while creating the archive. It is because
+@GNUTAR{}, unless told explicitly not to do so, removes some directory
+prefixes from file names before storing them in the archive
+(@xref{absolute}, for more information). In other
+words, in verbose mode @GNUTAR{} shows @dfn{file names} when creating
+an archive and @dfn{member names} when listing it. Consider this
+example:
+
+@smallexample
+@group
+$ @kbd{tar cfv archive /etc/mail}
+tar: Removing leading `/' from member names
+/etc/mail/
+/etc/mail/sendmail.cf
+/etc/mail/aliases
+$ @kbd{tar tf archive}
+etc/mail/
+etc/mail/sendmail.cf
+etc/mail/aliases
+@end group
+@end smallexample
+
+@opindex show-stored-names
+ This default behavior can sometimes be inconvenient. You can force
+@GNUTAR{} show member names when creating archive by supplying
+@option{--show-stored-names} option.
+
+@table @option
+@item --show-stored-names
+Print member (as opposed to @emph{file}) names when creating the archive.
+@end table
+
+@cindex File name arguments, using @option{--list} with
+@opindex list, using with file name arguments
+You can specify one or more individual member names as arguments when
+using @samp{list}. In this case, @command{tar} will only list the
+names of members you identify. For example, @w{@kbd{tar --list
+--file=afiles.tar apple}} would only print @file{apple}.
+
+@FIXME{we hope the relevant aspects of this will change:}Because
+@command{tar} preserves paths, file names must be specified as they appear
+in the archive (ie., relative to the directory from which the archive
+was created). Therefore, it is essential when specifying member names
+to @command{tar} that you give the exact member names. For example,
+@w{@kbd{tar --list --file=bfiles birds}} would produce an error message
+something like @samp{tar: birds: Not found in archive}, because there is
+no member named @file{birds}, only one named @file{./birds}. While the
+names @file{birds} and @file{./birds} name the same file, @emph{member}
+names are compared using a simplistic name comparison, in which an exact
+match is necessary. @xref{absolute}.
+
+However, @w{@kbd{tar --list --file=collection.tar folk}} would respond
+with @file{folk}, because @file{folk} is in the archive file
+@file{collection.tar}. If you are not sure of the exact file name, try
+listing all the files in the archive and searching for the one you
+expect to find; remember that if you use @option{--list} with no file
+names as arguments, @command{tar} will print the names of all the members
+stored in the specified archive.
@menu
-* Comparing Directories:: Using Compare on Directories
+* list dir::
@end menu
-@node Comparing Directories, , ,
-@subsubsection Using Compare on Directories
+@node list dir
+@unnumberedsubsec Listing the Contents of a Stored Directory
-In addition to using @samp{+compare} to compare text files, you can
-use @samp{+compare} to compare directories. To illustrate this,
-re-create the examples above using your home directory as the working
-directory, and using the archive file @file{~/music} instead of the
-archive file @file{~/practice/records}.
+To get information about the contents of an archived directory,
+use the directory name as a file name argument in conjunction with
+@option{--list} (@option{-t}). To find out file attributes, include the
+@option{--verbose} (@option{-v}) option.
-First, change into your home directory (@samp{cd ~}). Then, try the
-above example using @file{music} as the specified archive file, and
-@file{practice} as a file-name argument.
+For example, to find out about files in the directory @file{practice}, in
+the archive file @file{music.tar}, type:
-@example
-% tar +compare +verbose +file=music practice
-@end example
+@smallexample
+$ @kbd{tar --list --verbose --file=music.tar practice}
+@end smallexample
-@noindent
-If you have been following along with the tutorial, @code{tar} will
-respond:
-
-@example
-practice
-practice/blues
-practice/blues: mod time differs
-practice/blues: size differs
-practice/folk
-practice/jazz
-practice/jazz: does not exist
-practice/records
-@end example
+@command{tar} responds:
-@node Adding to Archives, Concatenate, Listing Archive Contents, Tutorial
-@section Adding Files to Existing Archives
+@smallexample
+drwxrwxrwx myself user 0 1990-05-31 21:49 practice/
+-rw-r--r-- myself user 42 1990-05-21 13:29 practice/blues
+-rw-r--r-- myself user 62 1990-05-23 10:55 practice/folk
+-rw-r--r-- myself user 40 1990-05-21 13:30 practice/jazz
+-rw-r--r-- myself user 10240 1990-05-31 21:49 practice/collection.tar
+@end smallexample
-@c >>> we want people to use the script for backups, so I an not going to
-@c >>> use backups as an explanation in the tutorial. (people can still
-@c >>> do it if they really want to) -ringo
+When you use a directory name as a file name argument, @command{tar} acts on
+all the files (including sub-directories) in that directory.
-While you can use @code{tar} to create a new archive every time you
-want to store a file, it is more sometimes efficient to add files to
-an existing archive.
+@node extract
+@section How to Extract Members from an Archive
+@UNREVISED
+@cindex Extraction
+@cindex Retrieving files from an archive
+@cindex Resurrecting files from an archive
-To add new files to an existing archive, use the @samp{+add-file},
-@samp{+append} or @samp{-r} operation. To add newer versions of
-archive members to an archive, use the @samp{+update} or @samp{-u}
-operation.
+@opindex extract
+Creating an archive is only half the job---there is no point in storing
+files in an archive if you can't retrieve them. The act of retrieving
+members from an archive so they can be used and manipulated as
+unarchived files again is called @dfn{extraction}. To extract files
+from an archive, use the @option{--extract} (@option{--get} or
+@option{-x}) operation. As with @option{--create}, specify the name
+of the archive with @option{--file} (@option{-f}) option. Extracting
+an archive does not modify the archive in any way; you can extract it
+multiple times if you want or need to.
+
+Using @option{--extract}, you can extract an entire archive, or specific
+files. The files can be directories containing other files, or not. As
+with @option{--create} (@option{-c}) and @option{--list} (@option{-t}), you may use the short or the
+long form of the operation without affecting the performance.
@menu
-* Append:: Appending Files to an Archive
-* Update:: Updating Files in an Archive
+* extracting archives::
+* extracting files::
+* extract dir::
+* extracting untrusted archives::
+* failing commands::
@end menu
-@node Append, Update, Adding to Archives, Adding to Archives
-@subsection Appending Files to an Archive
+@node extracting archives
+@subsection Extracting an Entire Archive
-The simplest method of adding a file to an existing archive is the
-@samp{+add-file}, @samp{-r} or @samp{+append} operation, which writes
-files into the archive without regard to whether or not they are
-already archive members. When you use @samp{+add-file} you must use
-file-name arguments; there is no default. If you specify a file that
-is already stored in the archive, @code{tar} adds another copy of the
-file to the archive.
+To extract an entire archive, specify the archive file name only, with
+no individual file names as arguments. For example,
-If you have been following the previous examples, you should have a
-text file called @file{~/practice/rock} which has not been stored in
-either the archive file @file{~/practice/records}, or the archive file
-@file{~/music}. To add @file{rock} to @file{records}, first make
-@file{practice} the working directory (@samp{cd practice}). Then:
+@smallexample
+$ @kbd{tar -xvf collection.tar}
+@end smallexample
-@itemize @bullet
-@item
-Invoke @code{tar} and specify the @samp{+add-file} operation
-(@samp{+add-file}, @samp{-r} or @samp{+append})
+@noindent
+produces this:
-@item
-Specify the archive to which the file will be added
-(@samp{+file=@var{archive-name}} or @samp{-f @var{archive-name}})
+@smallexample
+-rw-r--r-- me user 28 1996-10-18 16:31 jazz
+-rw-r--r-- me user 21 1996-09-23 16:44 blues
+-rw-r--r-- me user 20 1996-09-23 16:44 folk
+@end smallexample
-@item
-Specify the files to be added to the archive, using file-name
-arguments
-@end itemize
+@node extracting files
+@subsection Extracting Specific Files
-@noindent
-For example:
+To extract specific archive members, give their exact member names as
+arguments, as printed by @option{--list} (@option{-t}). If you had mistakenly deleted
+one of the files you had placed in the archive @file{collection.tar}
+earlier (say, @file{blues}), you can extract it from the archive without
+changing the archive's structure. Its contents will be identical to the
+original file @file{blues} that you deleted.
+
+First, make sure you are in the @file{practice} directory, and list the
+files in the directory. Now, delete the file, @samp{blues}, and list
+the files in the directory again.
+
+You can now extract the member @file{blues} from the archive file
+@file{collection.tar} like this:
-@example
-% tar +add-file +file=records rock
-@end example
+@smallexample
+$ @kbd{tar --extract --file=collection.tar blues}
+@end smallexample
@noindent
-If you list the archive members in @file{records}, you will see that
-@file{rock} has been added to the archive:
+If you list the files in the directory again, you will see that the file
+@file{blues} has been restored, with its original permissions, data modification
+times, and owner.@FIXME{This is only accidentally true, but not in
+general. In most cases, one has to be root for restoring the owner, and
+use a special option for restoring permissions. Here, it just happens
+that the restoring user is also the owner of the archived members, and
+that the current @code{umask} is compatible with original permissions.}
+(These parameters will be identical to those which
+the file had when you originally placed it in the archive; any changes
+you may have made before deleting the file from the file system,
+however, will @emph{not} have been made to the archive member.) The
+archive file, @samp{collection.tar}, is the same as it was before you
+extracted @samp{blues}. You can confirm this by running @command{tar} with
+@option{--list} (@option{-t}).
+
+@FIXME{we hope this will change:}Remember that as with other operations,
+specifying the exact member name is important. @w{@kbd{tar --extract
+--file=bfiles.tar birds}} will fail, because there is no member named
+@file{birds}. To extract the member named @file{./birds}, you must
+specify @w{@kbd{tar --extract --file=bfiles.tar ./birds}}. To find the
+exact member names of the members of an archive, use @option{--list} (@option{-t})
+(@pxref{list}).
+
+You can extract a file to standard output by combining the above options
+with the @option{--to-stdout} (@option{-O}) option (@pxref{Writing to Standard
+Output}).
+
+If you give the @option{--verbose} option, then @option{--extract}
+will print the names of the archive members as it extracts them.
+
+@node extract dir
+@subsection Extracting Files that are Directories
+
+Extracting directories which are members of an archive is similar to
+extracting other files. The main difference to be aware of is that if
+the extracted directory has the same name as any directory already in
+the working directory, then files in the extracted directory will be
+placed into the directory of the same name. Likewise, if there are
+files in the pre-existing directory with the same names as the members
+which you extract, the files from the extracted archive will replace
+the files already in the working directory (and possible
+subdirectories). This will happen regardless of whether or not the
+files in the working directory were more recent than those extracted
+(there exist, however, special options that alter this behavior
+@pxref{Writing}).
+
+However, if a file was stored with a directory name as part of its file
+name, and that directory does not exist under the working directory when
+the file is extracted, @command{tar} will create the directory.
+
+We can demonstrate how to use @option{--extract} to extract a directory
+file with an example. Change to the @file{practice} directory if you
+weren't there, and remove the files @file{folk} and @file{jazz}. Then,
+go back to the parent directory and extract the archive
+@file{music.tar}. You may either extract the entire archive, or you may
+extract only the files you just deleted. To extract the entire archive,
+don't give any file names as arguments after the archive name
+@file{music.tar}. To extract only the files you deleted, use the
+following command:
+
+@smallexample
+$ @kbd{tar -xvf music.tar practice/folk practice/jazz}
+practice/folk
+practice/jazz
+@end smallexample
-@example
-% tar +list +file=records
-blues
-folk
-jazz
-rock
-@end example
-
-@c <<< this should be some kind of node.
-
-You can use @samp{+add-file} to keep archive members current with
-active files. Because @samp{+add-file} stores a file whether or not
-there is already an archive member with the same file name, you can
-use @samp{+add-file} to add newer versions of archive members to an
-archive. When you extract the file, only the version stored last will
-wind up in the file system. Because @samp{tar +extract} extracts
-files from an archive in sequence, and overwrites files with the same
-name in the file system, if a file name appears more than once in an
-archive the last version of the file will overwrite the previous
-versions which have just been extracted.
-
-If you recall from the examples using @samp{+compare} above,
-@file{blues} was changed after the archive @file{records} was created.
-It is simple, however, to use @samp{+add-file} to add the new version
-of @file{blues} to @file{records}:
-
-@example
-% tar +add-file +verbose +file=records blues
-blues
-@end example
+@noindent
+If you were to specify two @option{--verbose} (@option{-v}) options, @command{tar}
+would have displayed more detail about the extracted files, as shown
+in the example below:
+
+@smallexample
+$ @kbd{tar -xvvf music.tar practice/folk practice/jazz}
+-rw-r--r-- me user 28 1996-10-18 16:31 practice/jazz
+-rw-r--r-- me user 20 1996-09-23 16:44 practice/folk
+@end smallexample
@noindent
-If you now list the contents of the archive, you will obtain the following:
+Because you created the directory with @file{practice} as part of the
+file names of each of the files by archiving the @file{practice}
+directory as @file{practice}, you must give @file{practice} as part
+of the file names when you extract those files from the archive.
-@example
-% tar +list -f records
-blues
-folk
-jazz
-rock
-blues
-@end example
-
-@noindent
-The newest version of @file{blues} is at the end of the archive. When
-the files in @file{records} are extracted, the newer version of
-@file{blues} (which has the same name as the older) will overwrite the
-version stored first. When @samp{tar +extract} is finished, only the
-newer version of @file{blues} is in the file system. <<<xref
-keep-old-files>>>
-
-@node Update, , Append, Adding to Archives
-@subsection Updating Files in an Archive
-
-To keep archive members up to date with their counterparts of the same
-name in the file system, use the @samp{+update} or @samp{-u}
-operation. @samp{tar +update} adds a specified file to an archive if
-no file of that name is already stored in the archive. If there is
-already an archive member with the same name, @code{tar} checks the
-modification date of the archive member, and adds the file only if its
-modification date is later. If a file is stored in the archive but no
-longer exists under the same name in the active file system,
-@code{tar} reports an error.
-
-You could use the @samp{+add-file} option to keep an archive current,
-but do so you would either have to use the @samp{+compare} and
-@samp{+list} options to determine what files needed to be re-archived
-(which could waste a lot of time), or you would have to be willing to
-add identical copies of already archived files to the archive (which
-could waste a lot of space).
-
-You must use file-name arguments with the @samp{+update}
-operation---if you don't specify any files, @code{tar} won't act on
-any files.
-
-To see the @samp{+update} option at work, create a new file,
-@file{~/practice/classical}, and modify the file
-@file{~/practice/blues} (you can use a text editor, such as Emacs, to
-do both these things). Then, with @file{practice} as your working
-directory, invoke @samp{tar +update} using the names of all the files
-in the practice directory as file-name arguments, and specifying the
-@samp{+verbose} option:
-
-@example
-% tar +update +verbose +file=records blues folk rock classical
-blues
-classical
-%
-@end example
-
-@noindent
-Because you specified verbose mode, @code{tar} printed out the names
-of the files it acted on. If you now list the archive members of the
-archive, (@samp{tar +list +file=records}), you will see that the file
-@file{classical} and another version of the file @file{blues} have
-been added to @file{records}.
-
-Note: When you update an archive, @code{tar} does not overwrite old
-archive members when it stores newer versions of a file. This is
-because archive members appear in an archive in the order in which
-they are stored, and some archive devices do not allow writing in the
-middle of an archive.
-
-@node Concatenate, Extracting Files Example, Adding to Archives, Tutorial
-@comment node-name, next, previous, up
-@section Concatenating Archives
-
-To concatenate archive files, use @samp{tar +concatenate} or @samp{tar
--A}. This operation adds other archives to the end of an archive.
-While it may seem intuitive to concatenate archives using @code{cat},
-the utility for adding files together, archive files which have been
-"catted" together cannot be read properly by @code{tar}. Archive
-files incorporate an end of file marker---if archives are concatenated
-using @code{cat}, this marker will appear before the end of the new
-archive. This will interfere with operations on that archive.
-@c <<<xref ignore-zeros>>>
-
-In earlier examples, you stored the @file{~/practice} directory in an
-archive file, @file{~/music}. If you have been following the
-examples, you have since changed the contents of the @file{~/practice}
-directory. There is a current version of the files in the
-@file{practice} directory, however, stored in the archive file
-@file{~/practice/records}.
-
-To store current versions of the files in @file{practice} in the
-archive file @file{music}, you can use @samp{tar +concatenate} to add
-the archive file @file{~/practice/records} to @file{music}. First,
-make sure you are in your home directory (@samp{cd ~}). Then:
+@FIXME{IMPORTANT! show the final structure, here. figure out what it
+will be.}
-@itemize @bullet
-@item
-Invoke @code{tar}, and specify the @samp{+concatenate} operation
-(@samp{-A} or @samp{+concatenate})
+@node extracting untrusted archives
+@subsection Extracting Archives from Untrusted Sources
-@item
-Specify the archive file to be added to
-(@samp{+file=@var{archive-name}} or @samp{-f @var{archive-name}})
+Extracting files from archives can overwrite files that already exist.
+If you receive an archive from an untrusted source, you should make a
+new directory and extract into that directory, so that you don't have
+to worry about the extraction overwriting one of your existing files.
+For example, if @file{untrusted.tar} came from somewhere else on the
+Internet, and you don't necessarily trust its contents, you can
+extract it as follows:
-@item
-Specify the archives to be added, using file-name arguments. In this
-case, the file-name arguments are, unusually, the names of archive
-files. (Remember to include the path in the archive name, if the
-archive file is not in your working directory.)
-@end itemize
+@smallexample
+$ @kbd{mkdir newdir}
+$ @kbd{cd newdir}
+$ @kbd{tar -xvf ../untrusted.tar}
+@end smallexample
-@example
-% cd ~
-% tar +concatenate +file=music practice/records
-@end example
+It is also a good practice to examine contents of the archive
+before extracting it, using @option{--list} (@option{-t}) option, possibly combined
+with @option{--verbose} (@option{-v}).
-If you now list the contents of the @file{music}, you see it now
-contains the archive members of @file{practice/records}:
+@node failing commands
+@subsection Commands That Will Fail
-@example
-%tar +list +file=music
-blues
-folk
-jazz
-rock
-blues
-practice/blues
+Here are some sample commands you might try which will not work, and why
+they won't work.
+
+If you try to use this command,
+
+@smallexample
+$ @kbd{tar -xvf music.tar folk jazz}
+@end smallexample
+
+@noindent
+you will get the following response:
+
+@smallexample
+tar: folk: Not found in archive
+tar: jazz: Not found in archive
+$
+@end smallexample
+
+@noindent
+This is because these files were not originally @emph{in} the parent
+directory @file{..}, where the archive is located; they were in the
+@file{practice} directory, and their file names reflect this:
+
+@smallexample
+$ @kbd{tar -tvf music.tar}
practice/folk
practice/jazz
practice/rock
-practice/blues
-practice/classical
-@end example
+@end smallexample
-@node Deleting Files, , , Tutorial
-@comment node-name, next, previous, up
-@section Deleting Files From an Archive
+@FIXME{make sure the above works when going through the examples in
+order...}
-In some instances, you may want to remove some files from an archive
-stored on disk
+@noindent
+Likewise, if you try to use this command,
-@quotation
-@emph{Caution:} you should never delete files from an archive stored
-on tape---because of the linear nature of tape storage, doing this is
-likely to scramble the archive.
-@end quotation
+@smallexample
+$ @kbd{tar -tvf music.tar folk jazz}
+@end smallexample
-To remove archive members from an archive, use the @samp{+delete}
-operation. You must specify the names of files to be removed as
-file-name arguments. All versions of the named file are removed from
-the archive.
+@noindent
+you would get a similar response. Members with those names are not in the
+archive. You must use the correct member names in order to extract the
+files from the archive.
+
+If you have forgotten the correct names of the files in the archive,
+use @w{@kbd{tar --list --verbose}} to list them correctly.
+
+@FIXME{more examples, here? hag thinks it's a good idea.}
+
+@node going further
+@section Going Further Ahead in this Manual
+
+@FIXME{need to write up a node here about the things that are going to
+be in the rest of the manual.}
+
+@node tar invocation
+@chapter Invoking @GNUTAR{}
+@UNREVISED
+
+This chapter is about how one invokes the @GNUTAR{}
+command, from the command synopsis (@pxref{Synopsis}). There are
+numerous options, and many styles for writing them. One mandatory
+option specifies the operation @command{tar} should perform
+(@pxref{Operation Summary}), other options are meant to detail how
+this operation should be performed (@pxref{Option Summary}).
+Non-option arguments are not always interpreted the same way,
+depending on what the operation is.
+
+You will find in this chapter everything about option styles and rules for
+writing them (@pxref{Styles}). On the other hand, operations and options
+are fully described elsewhere, in other chapters. Here, you will find
+only synthetic descriptions for operations and options, together with
+pointers to other parts of the @command{tar} manual.
+
+Some options are so special they are fully described right in this
+chapter. They have the effect of inhibiting the normal operation of
+@command{tar} or else, they globally alter the amount of feedback the user
+receives about what is going on. These are the @option{--help} and
+@option{--version} (@pxref{help}), @option{--verbose} (@pxref{verbose})
+and @option{--interactive} options (@pxref{interactive}).
-Execution of the @samp{+delete} operation can be very slow.
+@menu
+* Synopsis::
+* using tar options::
+* Styles::
+* All Options::
+* help::
+* defaults::
+* verbose::
+* interactive::
+@end menu
-To delete all versions of the file @file{blues} from the archive
-@file{records} in the @file{practice} directory, make sure you are in
-that directory, and then:
+@node Synopsis
+@section General Synopsis of @command{tar}
+
+The @GNUTAR{} program is invoked as either one of:
+
+@smallexample
+@kbd{tar @var{option}@dots{} [@var{name}]@dots{}}
+@kbd{tar @var{letter}@dots{} [@var{argument}]@dots{} [@var{option}]@dots{} [@var{name}]@dots{}}
+@end smallexample
+
+The second form is for when old options are being used.
+
+You can use @command{tar} to store files in an archive, to extract them from
+an archive, and to do other types of archive manipulation. The primary
+argument to @command{tar}, which is called the @dfn{operation}, specifies
+which action to take. The other arguments to @command{tar} are either
+@dfn{options}, which change the way @command{tar} performs an operation,
+or file names or archive members, which specify the files or members
+@command{tar} is to act on.
+
+You can actually type in arguments in any order, even if in this manual
+the options always precede the other arguments, to make examples easier
+to understand. Further, the option stating the main operation mode
+(the @command{tar} main command) is usually given first.
+
+Each @var{name} in the synopsis above is interpreted as an archive member
+name when the main command is one of @option{--compare}
+(@option{--diff}, @option{-d}), @option{--delete}, @option{--extract}
+(@option{--get}, @option{-x}), @option{--list} (@option{-t}) or
+@option{--update} (@option{-u}). When naming archive members, you
+must give the exact name of the member in the archive, as it is
+printed by @option{--list}. For @option{--append} (@option{-r}) and
+@option{--create} (@option{-c}), these @var{name} arguments specify
+the names of either files or directory hierarchies to place in the archive.
+These files or hierarchies should already exist in the file system,
+prior to the execution of the @command{tar} command.
+
+@command{tar} interprets relative file names as being relative to the
+working directory. @command{tar} will make all file names relative
+(by removing leading slashes when archiving or restoring files),
+unless you specify otherwise (using the @option{--absolute-names}
+option). @xref{absolute}, for more information about
+@option{--absolute-names}.
+
+If you give the name of a directory as either a file name or a member
+name, then @command{tar} acts recursively on all the files and directories
+beneath that directory. For example, the name @file{/} identifies all
+the files in the file system to @command{tar}.
+
+The distinction between file names and archive member names is especially
+important when shell globbing is used, and sometimes a source of confusion
+for newcomers. @xref{Wildcards}, for more information about globbing.
+The problem is that shells may only glob using existing files in the
+file system. Only @command{tar} itself may glob on archive members, so when
+needed, you must ensure that wildcard characters reach @command{tar} without
+being interpreted by the shell first. Using a backslash before @samp{*}
+or @samp{?}, or putting the whole argument between quotes, is usually
+sufficient for this.
+
+Even if @var{name}s are often specified on the command line, they
+can also be read from a text file in the file system, using the
+@option{--files-from=@var{file-of-names}} (@option{-T @var{file-of-names}}) option.
+
+If you don't use any file name arguments, @option{--append} (@option{-r}),
+@option{--delete} and @option{--concatenate} (@option{--catenate},
+@option{-A}) will do nothing, while @option{--create} (@option{-c})
+will usually yield a diagnostic and inhibit @command{tar} execution.
+The other operations of @command{tar} (@option{--list},
+@option{--extract}, @option{--compare}, and @option{--update})
+will act on the entire contents of the archive.
+
+@cindex exit status
+@cindex return status
+Besides successful exits, @GNUTAR{} may fail for
+many reasons. Some reasons correspond to bad usage, that is, when the
+@command{tar} command is improperly written. Errors may be
+encountered later, while encountering an error processing the archive
+or the files. Some errors are recoverable, in which case the failure
+is delayed until @command{tar} has completed all its work. Some
+errors are such that it would not meaningful, or at least risky, to
+continue processing: @command{tar} then aborts processing immediately.
+All abnormal exits, whether immediate or delayed, should always be
+clearly diagnosed on @code{stderr}, after a line stating the nature of
+the error.
+
+@GNUTAR{} returns only a few exit statuses. I'm really
+aiming simplicity in that area, for now. If you are not using the
+@option{--compare} @option{--diff}, @option{-d}) option, zero means
+that everything went well, besides maybe innocuous warnings. Nonzero
+means that something went wrong. Right now, as of today, ``nonzero''
+is almost always 2, except for remote operations, where it may be
+128.
+
+@node using tar options
+@section Using @command{tar} Options
+
+@GNUTAR{} has a total of eight operating modes which
+allow you to perform a variety of tasks. You are required to choose
+one operating mode each time you employ the @command{tar} program by
+specifying one, and only one operation as an argument to the
+@command{tar} command (two lists of four operations each may be found
+at @ref{frequent operations} and @ref{Operations}). Depending on
+circumstances, you may also wish to customize how the chosen operating
+mode behaves. For example, you may wish to change the way the output
+looks, or the format of the files that you wish to archive may require
+you to do something special in order to make the archive look right.
+
+You can customize and control @command{tar}'s performance by running
+@command{tar} with one or more options (such as @option{--verbose}
+(@option{-v}), which we used in the tutorial). As we said in the
+tutorial, @dfn{options} are arguments to @command{tar} which are (as
+their name suggests) optional. Depending on the operating mode, you
+may specify one or more options. Different options will have different
+effects, but in general they all change details of the operation, such
+as archive format, archive name, or level of user interaction. Some
+options make sense with all operating modes, while others are
+meaningful only with particular modes. You will likely use some
+options frequently, while you will only use others infrequently, or
+not at all. (A full list of options is available in @pxref{All Options}.)
+
+@vrindex TAR_OPTIONS, environment variable
+@anchor{TAR_OPTIONS}
+The @env{TAR_OPTIONS} environment variable specifies default options to
+be placed in front of any explicit options. For example, if
+@code{TAR_OPTIONS} is @samp{-v --unlink-first}, @command{tar} behaves as
+if the two options @option{-v} and @option{--unlink-first} had been
+specified before any explicit options. Option specifications are
+separated by whitespace. A backslash escapes the next character, so it
+can be used to specify an option containing whitespace or a backslash.
+
+Note that @command{tar} options are case sensitive. For example, the
+options @option{-T} and @option{-t} are different; the first requires an
+argument for stating the name of a file providing a list of @var{name}s,
+while the second does not require an argument and is another way to
+write @option{--list} (@option{-t}).
+
+In addition to the eight operations, there are many options to
+@command{tar}, and three different styles for writing both: long (mnemonic)
+form, short form, and old style. These styles are discussed below.
+Both the options and the operations can be written in any of these three
+styles.
+
+@FIXME{menu at end of this node. need to think of an actual outline
+for this chapter; probably do that after stuff from chapter 4 is
+incorporated.}
+
+@node Styles
+@section The Three Option Styles
+
+There are three styles for writing operations and options to the command
+line invoking @command{tar}. The different styles were developed at
+different times during the history of @command{tar}. These styles will be
+presented below, from the most recent to the oldest.
+
+Some options must take an argument. (For example, @option{--file}
+(@option{-f})) takes the name of an archive file as an argument. If
+you do not supply an archive file name, @command{tar} will use a
+default, but this can be confusing; thus, we recommend that you always
+supply a specific archive file name.) Where you @emph{place} the
+arguments generally depends on which style of options you choose. We
+will detail specific information relevant to each option style in the
+sections on the different option styles, below. The differences are
+subtle, yet can often be very important; incorrect option placement
+can cause you to overwrite a number of important files. We urge you
+to note these differences, and only use the option style(s) which
+makes the most sense to you until you feel comfortable with the others.
+
+Some options @emph{may} take an argument (currently, there are
+two such options: @option{--backup} and @option{--occurrence}). Such
+options may have at most long and short forms, they do not have old style
+equivalent. The rules for specifying an argument for such options
+are stricter than those for specifying mandatory arguments. Please,
+pay special attention to them.
-@itemize @bullet
-@item
-List the contents of the archive file @file{records} (see above for
-the steps involved) to insure that the file(s) you wish to delete are
-stored in the archive. (This step is optional)
+@menu
+* Mnemonic Options:: Mnemonic Option Style
+* Short Options:: Short Option Style
+* Old Options:: Old Option Style
+* Mixing:: Mixing Option Styles
+@end menu
-@item
-Invoke @code{tar} and specify the @samp{+delete} operation
-(@samp{+delete}).
+@node Mnemonic Options
+@subsection Mnemonic Option Style
+
+@FIXME{have to decide whether or not to replace other occurrences of
+"mnemonic" with "long", or *ugh* vice versa.}
+
+Each option has at least one long (or mnemonic) name starting with two
+dashes in a row, e.g., @option{--list}. The long names are more clear than
+their corresponding short or old names. It sometimes happens that a
+single mnemonic option has many different different names which are
+synonymous, such as @option{--compare} and @option{--diff}. In addition,
+long option names can be given unique abbreviations. For example,
+@option{--cre} can be used in place of @option{--create} because there is no
+other mnemonic option which begins with @samp{cre}. (One way to find
+this out is by trying it and seeing what happens; if a particular
+abbreviation could represent more than one option, @command{tar} will tell
+you that that abbreviation is ambiguous and you'll know that that
+abbreviation won't work. You may also choose to run @samp{tar --help}
+to see a list of options. Be aware that if you run @command{tar} with a
+unique abbreviation for the long name of an option you didn't want to
+use, you are stuck; @command{tar} will perform the command as ordered.)
+
+Mnemonic options are meant to be obvious and easy to remember, and their
+meanings are generally easier to discern than those of their
+corresponding short options (see below). For example:
+
+@smallexample
+$ @kbd{tar --create --verbose --blocking-factor=20 --file=/dev/rmt0}
+@end smallexample
-@item
-Specify the name of the archive file that the file(s) will be deleted
-from (@samp{+file=@var{archive-name}} or @samp{-f @var{archive-name}})
+@noindent
+gives a fairly good set of hints about what the command does, even
+for those not fully acquainted with @command{tar}.
+
+Mnemonic options which require arguments take those arguments
+immediately following the option name. There are two ways of
+specifying a mandatory argument. It can be separated from the
+option name either by an equal sign, or by any amount of
+white space characters. For example, the @option{--file} option (which
+tells the name of the @command{tar} archive) is given a file such as
+@file{archive.tar} as argument by using any of the following notations:
+@option{--file=archive.tar} or @option{--file archive.tar}.
+
+In contrast, optional arguments must always be introduced using
+an equal sign. For example, the @option{--backup} option takes
+an optional argument specifying backup type. It must be used
+as @option{--backup=@var{backup-type}}.
+
+@node Short Options
+@subsection Short Option Style
+
+Most options also have a short option name. Short options start with
+a single dash, and are followed by a single character, e.g., @option{-t}
+(which is equivalent to @option{--list}). The forms are absolutely
+identical in function; they are interchangeable.
+
+The short option names are faster to type than long option names.
+
+Short options which require arguments take their arguments immediately
+following the option, usually separated by white space. It is also
+possible to stick the argument right after the short option name, using
+no intervening space. For example, you might write @w{@option{-f
+archive.tar}} or @option{-farchive.tar} instead of using
+@option{--file=archive.tar}. Both @option{--file=@var{archive-name}} and
+@w{@option{-f @var{archive-name}}} denote the option which indicates a
+specific archive, here named @file{archive.tar}.
+
+Short options which take optional arguments take their arguments
+immediately following the option letter, @emph{without any intervening
+white space characters}.
+
+Short options' letters may be clumped together, but you are not
+required to do this (as compared to old options; see below). When
+short options are clumped as a set, use one (single) dash for them
+all, e.g., @w{@samp{@command{tar} -cvf}}. Only the last option in
+such a set is allowed to have an argument@footnote{Clustering many
+options, the last of which has an argument, is a rather opaque way to
+write options. Some wonder if @acronym{GNU} @code{getopt} should not
+even be made helpful enough for considering such usages as invalid.}.
+
+When the options are separated, the argument for each option which requires
+an argument directly follows that option, as is usual for Unix programs.
+For example:
-@item
-Specify the files to be deleted, using file-name arguments.
+@smallexample
+$ @kbd{tar -c -v -b 20 -f /dev/rmt0}
+@end smallexample
+
+If you reorder short options' locations, be sure to move any arguments
+that belong to them. If you do not move the arguments properly, you may
+end up overwriting files.
+
+@node Old Options
+@subsection Old Option Style
+@UNREVISED
+
+Like short options, old options are single letters. However, old options
+must be written together as a single clumped set, without spaces separating
+them or dashes preceding them@footnote{Beware that if you precede options
+with a dash, you are announcing the short option style instead of the
+old option style; short options are decoded differently.}. This set
+of letters must be the first to appear on the command line, after the
+@command{tar} program name and some white space; old options cannot appear
+anywhere else. The letter of an old option is exactly the same letter as
+the corresponding short option. For example, the old option @samp{t} is
+the same as the short option @option{-t}, and consequently, the same as the
+mnemonic option @option{--list}. So for example, the command @w{@samp{tar
+cv}} specifies the option @option{-v} in addition to the operation @option{-c}.
+
+@FIXME{bob suggests having an uglier example. :-) }
+
+When options that need arguments are given together with the command,
+all the associated arguments follow, in the same order as the options.
+Thus, the example given previously could also be written in the old
+style as follows:
+
+@smallexample
+$ @kbd{tar cvbf 20 /dev/rmt0}
+@end smallexample
-@item
-List the contents of the archive file again---note that the files have
-been removed. (this step is also optional)
-@end itemize
+@noindent
+Here, @samp{20} is the argument of @option{-b} and @samp{/dev/rmt0} is
+the argument of @option{-f}.
-@example
-% tar +list +file=records
-blues
-folk
-jazz
-% tar +delete +file=records blues
-% tar +list +file=records
-folk
-jazz
-%
-@end example
+On the other hand, this old style syntax makes it difficult to match
+option letters with their corresponding arguments, and is often
+confusing. In the command @w{@samp{tar cvbf 20 /dev/rmt0}}, for example,
+@samp{20} is the argument for @option{-b}, @samp{/dev/rmt0} is the
+argument for @option{-f}, and @option{-v} does not have a corresponding
+argument. Even using short options like in @w{@samp{tar -c -v -b 20 -f
+/dev/rmt0}} is clearer, putting all arguments next to the option they
+pertain to.
-@node Wizardry, Archive Structure, Tutorial, Top
-@chapter Wizardry
+If you want to reorder the letters in the old option argument, be
+sure to reorder any corresponding argument appropriately.
-<<<This section needs to be written -ringo
+This old way of writing @command{tar} options can surprise even experienced
+users. For example, the two commands:
-@strong{To come:} using Unix file linking capability to recreate directory
-structures---linking files into one subdirectory and then tarring that
-directory.
+@smallexample
+@kbd{tar cfz archive.tar.gz file}
+@kbd{tar -cfz archive.tar.gz file}
+@end smallexample
-@strong{to come:} nice hairy example using absolute-paths, newer, etc.
+@noindent
+are quite different. The first example uses @file{archive.tar.gz} as
+the value for option @samp{f} and recognizes the option @samp{z}. The
+second example, however, uses @file{z} as the value for option
+@samp{f} --- probably not what was intended.
+
+Old options are kept for compatibility with old versions of @command{tar}.
+
+This second example could be corrected in many ways, among which the
+following are equivalent:
+
+@smallexample
+@kbd{tar -czf archive.tar.gz file}
+@kbd{tar -cf archive.tar.gz -z file}
+@kbd{tar cf archive.tar.gz -z file}
+@end smallexample
+
+@FIXME{still could explain this better; it's redundant:}
+
+@cindex option syntax, traditional
+As far as we know, all @command{tar} programs, @acronym{GNU} and
+non-@acronym{GNU}, support old options. @GNUTAR{}
+supports them not only for historical reasons, but also because many
+people are used to them. For compatibility with Unix @command{tar},
+the first argument is always treated as containing command and option
+letters even if it doesn't start with @samp{-}. Thus, @samp{tar c} is
+equivalent to @w{@samp{tar -c}:} both of them specify the
+@option{--create} (@option{-c}) command to create an archive.
+
+@node Mixing
+@subsection Mixing Option Styles
+
+All three styles may be intermixed in a single @command{tar} command,
+so long as the rules for each style are fully
+respected@footnote{Before @GNUTAR{} version 1.11.6,
+a bug prevented intermixing old style options with mnemonic options in
+some cases.}. Old style options and either of the modern styles of
+options may be mixed within a single @command{tar} command. However,
+old style options must be introduced as the first arguments only,
+following the rule for old options (old options must appear directly
+after the @command{tar} command and some white space). Modern options
+may be given only after all arguments to the old options have been
+collected. If this rule is not respected, a modern option might be
+falsely interpreted as the value of the argument to one of the old
+style options.
+
+For example, all the following commands are wholly equivalent, and
+illustrate the many combinations and orderings of option styles.
+
+@smallexample
+@kbd{tar --create --file=archive.tar}
+@kbd{tar --create -f archive.tar}
+@kbd{tar --create -farchive.tar}
+@kbd{tar --file=archive.tar --create}
+@kbd{tar --file=archive.tar -c}
+@kbd{tar -c --file=archive.tar}
+@kbd{tar -c -f archive.tar}
+@kbd{tar -c -farchive.tar}
+@kbd{tar -cf archive.tar}
+@kbd{tar -cfarchive.tar}
+@kbd{tar -f archive.tar --create}
+@kbd{tar -f archive.tar -c}
+@kbd{tar -farchive.tar --create}
+@kbd{tar -farchive.tar -c}
+@kbd{tar c --file=archive.tar}
+@kbd{tar c -f archive.tar}
+@kbd{tar c -farchive.tar}
+@kbd{tar cf archive.tar}
+@kbd{tar f archive.tar --create}
+@kbd{tar f archive.tar -c}
+@kbd{tar fc archive.tar}
+@end smallexample
+
+On the other hand, the following commands are @emph{not} equivalent to
+the previous set:
+
+@smallexample
+@kbd{tar -f -c archive.tar}
+@kbd{tar -fc archive.tar}
+@kbd{tar -fcarchive.tar}
+@kbd{tar -farchive.tarc}
+@kbd{tar cfarchive.tar}
+@end smallexample
+@noindent
+These last examples mean something completely different from what the
+user intended (judging based on the example in the previous set which
+uses long options, whose intent is therefore very clear). The first
+four specify that the @command{tar} archive would be a file named
+@option{-c}, @samp{c}, @samp{carchive.tar} or @samp{archive.tarc},
+respectively. The first two examples also specify a single non-option,
+@var{name} argument having the value @samp{archive.tar}. The last
+example contains only old style option letters (repeating option
+@samp{c} twice), not all of which are meaningful (eg., @samp{.},
+@samp{h}, or @samp{i}), with no argument value. @FIXME{not sure i liked
+the first sentence of this paragraph..}
+
+@node All Options
+@section All @command{tar} Options
+
+The coming manual sections contain an alphabetical listing of all
+@command{tar} operations and options, with brief descriptions and cross
+references to more in-depth explanations in the body of the manual.
+They also contain an alphabetically arranged table of the short option
+forms with their corresponding long option. You can use this table as
+a reference for deciphering @command{tar} commands in scripts.
-Piping one @code{tar} to another is an easy way to copy a directory's
-contents from one disk to another, while preserving the dates, modes, owners
-and link-structure of all the files therein.
+@menu
+* Operation Summary::
+* Option Summary::
+* Short Option Summary::
+@end menu
-@example
-cd sourcedirectory; tar cf - . | (cd targetdir; tar xf -)
-@end example
+@node Operation Summary
+@subsection Operations
-@noindent
-or
+@table @option
-<<< the following using standard input/output correct??
-@example
-cd sourcedirectory; tar +create +file=- . | (cd targetdir; tar +extract +file=-)
-@end example
+@opindex append, summary
+@item --append
+@itemx -r
-@noindent
+Appends files to the end of the archive. @xref{append}.
-Archive files can be used for transporting a group of files from one system
-to another: put all relevant files into an archive on one computer system,
-transfer the archive to another, and extract the contents there. The basic
-transfer medium might be magnetic tape, Internet FTP, or even electronic
-mail (though you must encode the archive with @code{uuencode} in order to
-transport it properly by mail). Both machines do not have to use the same
-operating system, as long as they both support the @code{tar} program.
-@findex uuencode
-<<< mention uuencode on a paragraph of its own
+@opindex catenate, summary
+@item --catenate
+@itemx -A
-<<<<<end construction>>>>>
+Same as @option{--concatenate}. @xref{concatenate}.
-@node Archive Structure, Reading and Writing, Wizardry, Top
-@chapter The Structure of an Archive
+@opindex compare, summary
+@item --compare
+@itemx -d
-While an archive may contain many files, the archive itself is a
-single ordinary file. Like any other file, an archive file can be
-written to a storage device such as a tape or disk, sent through a
-pipe or over a network, saved on the active file system, or even
-stored in another archive. An archive file is not easy to read or
-manipulate without using the @code{tar} utility or Tar mode in Emacs.
+Compares archive members with their counterparts in the file
+system, and reports differences in file size, mode, owner,
+modification date and contents. @xref{compare}.
+@opindex concatenate, summary
+@item --concatenate
+@itemx -A
-Physically, an archive consists of a series of file entries terminated
-by an end-of-archive entry, which consists of 512 zero bytes. A file
-entry usually describes one of the files in the archive (an
-@dfn{archive member}), and consists of a file header and the contents
-of the file. File headers contain file names and statistics, checksum
-information which @code{tar} uses to detect file corruption, and
-information about file types.
+Appends other @command{tar} archives to the end of the archive.
+@xref{concatenate}.
-More than archive member can have the same file name. One way this
-situation can occur is if more than one version of a file has been
-stored in the archive. For information about adding new versions of a
-file to an archive, @pxref{Modifying}.
+@opindex create, summary
+@item --create
+@itemx -c
-In addition to entries describing archive members, an archive may contain
-entries which @code{tar} itself uses to store information.
-@xref{Archive Label}, for an example of such an archive entry.
+Creates a new @command{tar} archive. @xref{create}.
-@menu
-* Old Style File Information:: Old Style File Information
-* Archive Label::
-* Format Variations::
-@end menu
+@opindex delete, summary
+@item --delete
-@node Old Style File Information, Archive Label, Archive Structure, Archive Structure
-@section Old Style File Information
-@cindex Format, old style
-@cindex Old style format
-@cindex Old style archives
+Deletes members from the archive. Don't try this on a archive on a
+tape! @xref{delete}.
-Archives record not only an archive member's contents, but also its
-file name or names, its access permissions, user and group, size in
-bytes, and last modification time. Some archives also record the file
-names in each archived directory, as well as other file and directory
-information.
-
-Certain old versions of @code{tar} cannot handle additional
-information recorded by newer @code{tar} programs. To create an
-archive which can be read by these old versions, specify the
-@samp{+old-archive} option in conjunction with the @samp{tar +create}
-operation. When you specify this option, @code{tar} leaves out
-information about directories, pipes, fifos, contiguous files, and
-device files, and specifies file ownership by group and user ids
-instead of names.
-
-The @samp{+old-archive} option is needed only if the archive must be
-readable by an older tape archive program which cannot handle the new format.
-Most @code{tar} programs do not have this limitation, so this option
-is seldom needed.
+@opindex diff, summary
+@item --diff
+@itemx -d
-@table @samp
-@item +old-archive
-@itemx -o
-@itemx +old
-@itemx +portable
-@c has portability been changed to portable?
-Creates an archive that can be read by an old @code{tar} program.
-Used in conjunction with the @samp{tar +create} operation.
-@end table
+Same @option{--compare}. @xref{compare}.
-@node Archive Label, Format Variations, Old Style File Information, Archive Structure
-@section Including a Label in the Archive
-@cindex Labeling an archive
-@cindex Labels on the archive media
+@opindex extract, summary
+@item --extract
+@itemx -x
-@c !! Should the arg to +label be a quoted string?? no - ringo
-To avoid problems caused by misplaced paper labels on the archive
-media, you can include a @dfn{label} entry---an archive member which
-contains the name of the archive---in the archive itself. Use the
-@samp{+label=@var{archive-label}} option in conjunction with the
-@samp{+create} operation to include a label entry in the archive as it
-is being created.
-
-If you create an archive using both @samp{+label=@var{archive-label}}
-and @samp{+multi-volume}, each volume of the archive will have an
-archive label of the form @samp{@var{archive-label} Volume @var{n}},
-where @var{n} is 1 for the first volume, 2 for the next, and so on.
-@xref{Multi-Volume Archives}, for information on creating multiple
-volume archives.
-
-If you extract an archive using @samp{+label=@var{archive-label}},
-@code{tar} will print an error if the archive label doesn't match the
-@var{archive-label} specified, and will then not extract the archive.
-You can include a regular expression in @var{archive-label}, in this
-case only.
-@c >>> why is a reg. exp. useful here? (to limit extraction to a
-@c >>>specific group? ie for multi-volume??? -ringo
-
-To find out an archive's label entry (or to find out if an archive has
-a label at all), use @samp{tar +list +verbose}. @code{tar} will print the
-label first, and then print archive member information, as in the
-example below:
-
-@example
-% tar +verbose +list +file=iamanarchive
-V--------- 0/0 0 Mar 7 12:01 1992 iamalabel--Volume Header--
--rw-rw-rw- ringo/user 40 May 21 13:30 1990 iamafilename
-@end example
+Extracts members from the archive into the file system. @xref{extract}.
-@table @samp
-@item +label=@var{archive-label}
-@itemx -V @var{archive-label}
-Includes an @dfn{archive-label} at the beginning of the archive when
-the archive is being created (when used in conjunction with the
-@samp{tar +create} operation). Checks to make sure the archive label
-matches the one specified (when used in conjunction with the @samp{tar
-+extract} operation.
-@end table
-@c was +volume
+@opindex get, summary
+@item --get
+@itemx -x
-@node Format Variations, , Archive Label, Archive Structure
-@section Format Variations
-@cindex Format Parameters
-@cindex Format Options
-@cindex Options to specify archive format.
+Same as @option{--extract}. @xref{extract}.
-Format parameters specify how an archive is written on the archive
-media. The best choice of format parameters will vary depending on
-the type and number of files being archived, and on the media used to
-store the archive.
+@opindex list, summary
+@item --list
+@itemx -t
-To specify format parameters when accessing or creating an archive,
-you can use the options described in the following sections. If you
-do not specify any format parameters, @code{tar} uses default
-parameters. You cannot modify a compressed archive. If you create an
-archive with the @samp{+block-size} option specified (@pxref{Blocking
-Factor}), you must specify that block-size when operating on the
-archive. @xref{Matching Format Parameters}, for other examples of
-format parameter considerations.
+Lists the members in an archive. @xref{list}.
+@opindex update, summary
+@item --update
+@itemx -u
-@menu
-* Multi-Volume Archives::
-* Sparse Files::
-* Blocking Factor::
-* Compressed Archives::
-@end menu
+@FIXME{It was: A combination of the @option{--compare} and
+@option{--append} operations. This is not true and rather misleading,
+as @option{--compare} (@option{--diff}, @option{-d}) does a lot more than @option{--update} (@option{-u}) for
+ensuring files are identical.} Adds files to the end of the archive,
+but only if they are newer than their counterparts already in the
+archive, or if they do not already exist in the archive.
+@xref{update}.
-@node Multi-Volume Archives, Sparse Files, Format Variations, Format Variations
-@subsection Archives Longer than One Tape or Disk
-@cindex Multi-volume archives
+@end table
-To create an archive that is larger than will fit on a single unit of
-the media, use the @samp{+multi-volume} option in conjunction with the
-@samp{tar +create} operation (@pxref{Creating Archives}). A
-@dfn{multi-volume} archive can be manipulated like any other archive
-(provided the @samp{+multi-volume} option is specified), but is stored
-on more than one tape or disk.
+@node Option Summary
+@subsection @command{tar} Options
+
+@table @option
+
+@opindex absolute-names, summary
+@item --absolute-names
+@itemx -P
+
+Normally when creating an archive, @command{tar} strips an initial
+@samp{/} from member names. This option disables that behavior.
+@xref{absolute}.
+
+@opindex after-date, summary
+@item --after-date
+
+(See @option{--newer}, @pxref{after})
+
+@opindex anchored, summary
+@item --anchored
+An exclude pattern must match an initial subsequence of the name's components.
+@xref{controlling pattern-matching with exclude}.
+
+@opindex atime-preserve, summary
+@item --atime-preserve
+@itemx --atime-preserve=replace
+@itemx --atime-preserve=system
+
+Attempt to preserve the access time of files when reading them. This
+option currently is effective only on files that you own, unless you
+have superuser privileges.
+
+@option{--atime-preserve=replace} remembers the access time of a file
+before reading it, and then restores the access time afterwards. This
+may cause problems if other programs are reading the file at the same
+time, as the times of their accesses will be lost. On most platforms
+restoring the access time also requires @command{tar} to restore the
+data modification time too, so this option may also cause problems if
+other programs are writing the file at the same time. (Tar attempts
+to detect this situation, but cannot do so reliably due to race
+conditions.) Worse, on most platforms restoring the access time also
+updates the status change time, which means that this option is
+incompatible with incremental backups.
+
+@option{--atime-preserve=system} avoids changing time stamps on files,
+without interfering with time stamp updates
+caused by other programs, so it works better with incremental backups.
+However, it requires a special @code{O_NOATIME} option from the
+underlying operating and file system implementation, and it also requires
+that searching directories does not update their access times. As of
+this writing (November 2005) this works only with Linux, and only with
+Linux kernels 2.6.8 and later. Worse, there is currently no reliable
+way to know whether this feature actually works. Sometimes
+@command{tar} knows that it does not work, and if you use
+@option{--atime-preserve=system} then @command{tar} complains and
+exits right away. But other times @command{tar} might think that the
+option works when it actually does not.
+
+Currently @option{--atime-preserve} with no operand defaults to
+@option{--atime-preserve=replace}, but this may change in the future
+as support for @option{--atime-preserve=system} improves.
+
+If your operating system does not support
+@option{--atime-preserve=system}, you might be able to preserve access
+times reliably by by using the @command{mount} command. For example,
+you can mount the file system read-only, or access the file system via
+a read-only loopback mount, or use the @samp{noatime} mount option
+available on some systems. However, mounting typically requires
+superuser privileges and can be a pain to manage.
+
+@opindex backup, summary
+@item --backup=@var{backup-type}
+
+Rather than deleting files from the file system, @command{tar} will
+back them up using simple or numbered backups, depending upon
+@var{backup-type}. @xref{backup}.
+
+@opindex block-number, summary
+@item --block-number
+@itemx -R
+
+With this option present, @command{tar} prints error messages for read errors
+with the block number in the archive file. @xref{block-number}.
+
+@opindex blocking-factor, summary
+@item --blocking-factor=@var{blocking}
+@itemx -b @var{blocking}
+
+Sets the blocking factor @command{tar} uses to @var{blocking} x 512 bytes per
+record. @xref{Blocking Factor}.
+
+@opindex bzip2, summary
+@item --bzip2
+@itemx -j
+
+This option tells @command{tar} to read or write archives through
+@code{bzip2}. @xref{gzip}.
+
+@opindex checkpoint, summary
+@item --checkpoint
+
+This option directs @command{tar} to print periodic checkpoint messages as it
+reads through the archive. Its intended for when you want a visual
+indication that @command{tar} is still running, but don't want to see
+@option{--verbose} output. @FIXME-xref{}
+
+@opindex check-links, summary
+@item --check-links
+@itemx -l
+If this option was given, @command{tar} will check the number of links
+dumped for each processed file. If this number does not match the
+total number of hard links for the file, a warning message will be
+output.
-When you specify @samp{+multi-volume}, @code{tar} does not report an
-error when it comes to the end of an archive volume (when reading), or
-the end of the media (when writing). Instead, it prompts you to load
-a new storage volume. If the archive is on a magnetic tape, you
-should change tapes when you see the prompt; if the archive is on a
-floppy disk, you should change disks; etc.
+Future versions will take @option{-l} as a short version of
+@option{--check-links}. However, current release still retains the old
+semantics for @option{-l}.
-You can read each individual volume of a multi-volume archive as if it
-were an archive by itself. For example, to list the contents of one
-volume, use @samp{tar +list}, without @samp{+multi-volume} specified.
-To extract an archive member from one volume (assuming it is described
-that volume), use @samp{tar +extract}, again without
-@samp{+multi-volume}.
+@xref{Changes}, for more information.
-If an archive member is split across volumes (ie. its entry begins on
-one volume of the media and ends on another), you need to specify
-@samp{+multi-volume} to extract it successfully. In this case, you
-should load the volume where the archive member starts, and use
-@samp{tar +extract +multi-volume}---@code{tar} will prompt for later
-volumes as it needs them. @xref{Extracting From Archives} for more
-information about extracting archives.
+@opindex compress, summary
+@opindex uncompress, summary
+@item --compress
+@itemx --uncompress
+@itemx -Z
-@samp{+info-script=@var{program-file}} is like @samp{+multi-volume},
-except that @code{tar} does not prompt you directly to change media
-volumes when a volume is full---instead, @code{tar} runs commands you
-have stored in @var{program-file}. This option can be used to
-broadcast messages such as @samp{someone please come change my tape}
-when performing unattended backups. When @var{program-file} is done,
-@code{tar} will assume that the media has been changed.
+@command{tar} will use the @command{compress} program when reading or
+writing the archive. This allows you to directly act on archives
+while saving space. @xref{gzip}.
+@opindex confirmation, summary
+@item --confirmation
-<<< There should be a sample program here, including an exit before
-<<< end.
+(See @option{--interactive}.) @xref{interactive}.
-@table @samp
-@item +multi-volume
-@itemx -M
-Creates a multi-volume archive, when used in conjunction with
-@samp{tar +create}. To perform any other operation on a multi-volume
-archive, specify @samp{+multi-volume} in conjunction with that
-operation.
+@opindex delay-directory-restore, summary
+@item --delay-directory-restore
-@item +info-script=@var{program-file}
-@itemx -F @var{program-file}
-Creates a multi-volume archive via a script. Used in conjunction with
-@samp{tar +create}.
-@end table
+Delay setting modification times and permissions of extracted
+directories until the end of extraction. @xref{Directory Modification Times and Permissions}.
-@node Sparse Files, Blocking Factor, Multi-Volume Archives, Format Variations
-@subsection Archiving Sparse Files
-@cindex Sparse Files
+@opindex dereference, summary
+@item --dereference
+@itemx -h
-A file is sparse if it contains blocks of zeros whose existance is
-recorded, but that have no space allocated on disk. When you specify
-the @samp{+sparse} option in conjunction with the @samp{+create}
-operation, @code{tar} tests all files for sparseness while archiving.
-If @code{tar} finds a file to be sparse, it uses a sparse
-representation of the file in the archive. @xref{Creating Archives},
-for more information about creating archives.
+When creating a @command{tar} archive, @command{tar} will archive the
+file that a symbolic link points to, rather than archiving the
+symlink. @xref{dereference}.
-@samp{+sparse} is useful when archiving files, such as dbm files,
-likely to contain many nulls. This option dramatically
-decreases the amount of space needed to store such an archive.
+@opindex directory, summary
+@item --directory=@var{dir}
+@itemx -C @var{dir}
-@quotation
-@strong{Please Note:} Always use @samp{+sparse} when performing file
-system backups, to avoid archiving the expanded forms of files stored
-sparsely in the system.@refill
+When this option is specified, @command{tar} will change its current directory
+to @var{dir} before performing any operations. When this option is used
+during archive creation, it is order sensitive. @xref{directory}.
-Even if your system has no no sparse files currently, some may be
-created in the future. If you use @samp{+sparse} while making file
-system backups as a matter of course, you can be assured the archive
-will always take no more space on the media than the files take on
-disk (otherwise, archiving a disk filled with sparse files might take
-hundreds of tapes).@refill
-<<< xref incremental when node name is set.
-@end quotation
+@opindex exclude, summary
+@item --exclude=@var{pattern}
-@code{tar} ignores the @samp{+sparse} option when reading an archive.
+When performing operations, @command{tar} will skip files that match
+@var{pattern}. @xref{exclude}.
-@table @samp
-@item +sparse
-@itemx -S
-Files stored sparsely in the file system are represented sparsely in
-the archive. Use in conjunction with write operations.
-@end table
+@opindex exclude-from, summary
+@item --exclude-from=@var{file}
+@itemx -X @var{file}
-@node Blocking Factor, Compressed Archives, Sparse Files, Format Variations
-@subsection The Blocking Factor of an Archive
-@cindex Blocking Factor
-@cindex Block Size
-@cindex Number of records per block
-@cindex Number of bytes per block
-@cindex Bytes per block
-@cindex Records per block
-
-The data in an archive is grouped into records, which are 512 bytes.
-Records are read and written in whole number multiples called
-@dfn{blocks}. The number of records in a block (ie. the size of a
-block in units of 512 bytes) is called the @dfn{blocking factor}. The
-@samp{+block-size=@var{number}} option specifies the blocking factor
-of an archive. The default blocking factor is typically 20 (ie.@:
-10240 bytes), but can be specified at installation. To find out the
-blocking factor of an existing archive, use @samp {tar +list
-+file=@var{archive-name}}. This may not work on some devices.
-
-Blocks are seperated by gaps, which waste space on the archive media.
-If you are archiving on magnetic tape, using a larger blocking factor
-(and therefore larger blocks) provides faster throughput and allows
-you to fit more data on a tape (because there are fewer gaps). If you
-are archiving on cartridge, a very large blocking factor (say 126 or
-more) greatly increases performance. A
-smaller blocking factor, on the other hand, may be usefull when
-archiving small files, to avoid archiving lots of nulls as @code{tar}
-fills out the archive to the end of the block. In general, the ideal block size
-depends on the size of the inter-block gaps on the tape you are using,
-and the average size of the files you are archiving. @xref{Creating
-Archives}, for information on writing archives.
-
-Archives with blocking factors larger than 20 cannot be read by very
-old versions of @code{tar}, or by some newer versions of @code{tar}
-running on old machines with small address spaces. With GNU
-@code{tar}, the blocking factor of an archive is limited only by the
-maximum block size of the device containing the archive, or by the
-amount of available virtual memory.
-
-If you use a non-default blocking factor when you create an archive,
-you must specify the same blocking factor when you modify that
-archive. Some archive devices will also require you to specify the
-blocking factor when reading that archive, however this is not
-typically the case. Usually, you can use @samp{tar +list} without
-specifying a blocking factor---@code{tar} reports a non-default block
-size and then lists the archive members as it would normally. To
-extract files from an archive with a non-standard blocking factor
-(particularly if you're not sure what the blocking factor is), you can
-usually use the {+read-full-blocks} option while specifying a blocking
-factor larger then the blocking factor of the archive (ie. @samp{tar
-+extract +read-full-blocks +block-size=300}. @xref{Listing Contents}
-for more information on the @samp{+list} operation.
-@xref{read-full-blocks} for a more detailed explanation of that
-option.
+Similar to @option{--exclude}, except @command{tar} will use the list of
+patterns in the file @var{file}. @xref{exclude}.
-@table @samp
-@item +block-size=@var{number}
-@itemx -b @var{number}
-Specifies the blocking factor of an archive. Can be used with any
-operation, but is usually not necessary with @samp{tar +list}.
-@end table
+@opindex exclude-caches, summary
+@item --exclude-caches
-@node Compressed Archives, , Blocking Factor, Format Variations
-@subsection Creating and Reading Compressed Archives
-@cindex Compressed archives
-@cindex Storing archives in compressed format
+Automatically excludes all directories
+containing a cache directory tag. @xref{exclude}.
-@samp{+compress} indicates an archive stored in compressed format.
-The @samp{+compress} option is useful in saving time over networks and
-space in pipes, and when storage space is at a premium.
-@samp{+compress} causes @code{tar} to compress when writing the
-archive, or to uncompress when reading the archive.
-
-To perform compression and uncompression on the archive, @code{tar}
-runs the @code{compress} utility. @code{tar} uses the default
-compression parameters; if you need to override them, avoid the
-@samp{+compress} option and run the @code{compress} utility
-explicitly. It is useful to be able to call the @code{compress}
-utility from within @code{tar} because the @code{compress} utility by
-itself cannot access remote tape drives.
-
-The @samp{+compress} option will not work in conjunction with the
-@samp{+multi-volume} option or the @samp{+add-file}, @samp{+update},
-@samp{+add-file} and @samp{+delete} operations. @xref{Modifying}, for
-more information on these operations.
-
-If there is no compress utility available, @code{tar} will report an
-error.
+@opindex file, summary
+@item --file=@var{archive}
+@itemx -f @var{archive}
-@samp{+compress-block} is like @samp{+compress}, but when used in
-conjunction with @samp{+create} also causes @code{tar} to pad the last
-block of the archive out to the next block boundary as it is written.
-This is useful with certain devices which require all write operations
-be a multiple of a specific size.
+@command{tar} will use the file @var{archive} as the @command{tar} archive it
+performs operations on, rather than @command{tar}'s compilation dependent
+default. @xref{file tutorial}.
-@quotation
-@strong{Please Note:} The @code{compress} program may be covered by a patent,
-and therefore we recommend you stop using it. We hope to have a
-different compress program in the future. We may change the name of
-this option at that time.
-@end quotation
+@opindex files-from, summary
+@item --files-from=@var{file}
+@itemx -T @var{file}
-@table @samp
-@item +compress
-@itemx +uncompress
-@itemx -z
-@itemx -Z
-When this option is specified, @code{tar} will compress (when writing
-an archive), or uncompress (when reading an archive). Used in
-conjunction with the @samp{+create}, @samp{+extract}, @samp{+list} and
-@samp{+compare} operations.
+@command{tar} will use the contents of @var{file} as a list of archive members
+or files to operate on, in addition to those specified on the
+command-line. @xref{files}.
-@item +compress-block
-@itemx -z -z
-Acts like @samp{+compress}, but pads the archive out to the next block
-boundary as it is written when used in conjunction with the
-@samp{+create} operation.
-@end table
+@opindex force-local, summary
+@item --force-local
-@c >>> MIB -- why not use -Z instead of -z -z ? -ringo
+Forces @command{tar} to interpret the filename given to @option{--file}
+as a local file, even if it looks like a remote tape drive name.
+@xref{local and remote archives}.
-@node Reading and Writing, Insuring Accuracy, Archive Structure, Top
-@chapter Reading and Writing Archives
+@opindex format, summary
+@item --format=@var{format}
-The @samp{+create} operation writes a new archive, and the
-@samp{+extract} operation reads files from an archive and writes them
-into the file system. You can use other @code{tar} operations to
-write new information into an existing archive (adding files to it,
-adding another archive to it, or deleting files from it), and you can
-read a list of the files in an archive without extracting it using the
-@samp{+list} operation.
+Selects output archive format. @var{Format} may be one of the
+following:
-@menu
-* Archive Name:: The name of an archive
-* Creating in Detail:: Creating in detail
-* Modifying:: Modifying archives
-* Listing Contents:: Listing the contents of an archive
-* Extracting From Archives:: Extracting files from an archive
-@end menu
+@table @samp
+@item v7
+Creates an archive that is compatible with Unix V7 @command{tar}.
-@node Archive Name, Creating in Detail, Reading and Writing, Reading and Writing
-@section The Name of an Archive
-@cindex Naming an archive
-@cindex Archive Name
-@cindex Directing output
-@cindex Where is the archive?
+@item oldgnu
+Creates an archive that is compatible with GNU @command{tar} version
+1.12 or earlier.
-An archive can be saved as a file in the file system, sent through a
-pipe or over a network, or written to an I/O device such as a tape or
-disk drive. To specify the name of the archive, use the
-@samp{+file=@var{archive-name}} option.
-
-An archive name can be the name of an ordinary file or the name of an
-I/O device. @code{tar} always needs an archive name---if you do not
-specify an archive name, the archive name comes from the environment
-variable @code{TAPE} or, if that variable is not specified, a default
-archive name, which is usually the name of tape unit zero (ie.
-/dev/tu00).
-
-If you use @file{-} as an @var{archive-name}, @code{tar} reads the
-archive from standard input (when listing or extracting files), or
-writes it to standard output (when creating an archive). If you use
-@file{-} as an @var{archive-name} when modifying an archive,
-@code{tar} reads the original archive from its standard input and
-writes the entire new archive to its standard output.
+@item gnu
+Creates archive in GNU tar 1.13 format. Basically it is the same as
+@samp{oldgnu} with the only difference in the way it handles long
+numeric fields.
-@c >>> MIB--does standard input and output redirection work with all
-@c >>> operations?
-@c >>> need example for standard input and output (screen and keyboard?)
+@item ustar
+Creates a @acronym{POSIX.1-1988} compatible archive.
-@cindex Standard input and output
-@cindex tar to standard input and output
+@item posix
+Creates a @acronym{POSIX.1-2001 archive}.
-To specify an archive file on a device attached to a remote machine,
-use the following:
+@end table
-@example
-+file=@var{hostname}:/@var{dev}/@var{file name}
-@end example
+@xref{Formats}, for a detailed discussion of these formats.
-@noindent
-@code{tar} will complete the remote connection, if possible, and
-prompt you for a username and password. If you use
-@samp{+file=@@@var{hostname}:/@var{dev}/@var{file-name}}, @code{tar}
-will complete the remote connection, if possible, using your username
-as the username on the remote machine.
+@opindex group, summary
+@item --group=@var{group}
-@c >>>MIB --- is this clear?
+Files added to the @command{tar} archive will have a group id of @var{group},
+rather than the group from the source file. @var{group} is first decoded
+as a group symbolic name, but if this interpretation fails, it has to be
+a decimal numeric group ID. @FIXME-xref{}
-@table @samp
-@item +file=@var{archive-name}
-@itemx -f @var{archive-name}
-Names the archive to create or operate on. Use in conjunction with
-any operation.
-@end table
+Also see the comments for the @option{--owner=@var{user}} option.
-@node Creating in Detail, Modifying, Archive Name, Reading and Writing
-@section Creating in Detail
-@c operations should probably have examples, not tables.
-@cindex Writing new archives
-@cindex Archive creation
+@opindex gzip, summary
+@opindex gunzip, summary
+@opindex ungzip, summary
+@item --gzip
+@itemx --gunzip
+@itemx --ungzip
+@itemx -z
-To create an archive, use @samp{tar +create}. To name the archive,
-use @samp{+file=@var{archive-name}} in conjunction with the
-@samp{+create} operation (@pxref{Archive Name}). If you do not name
-the archive, @code{tar} uses the value of the environment variable
-@code{TAPE} as the file name for the archive, or, if that is not
-available, @code{tar} uses a default archive name, usually that for tape
-unit zero. @xref{Archive Name}, for more information about specifying
-an archive name.
+This option tells @command{tar} to read or write archives through
+@command{gzip}, allowing @command{tar} to directly operate on several
+kinds of compressed archives transparently. @xref{gzip}.
-The following example creates an archive named @file{stooges},
-containing the files @file{larry}, @file{moe} and @file{curley}:
+@opindex help, summary
+@item --help
-@example
-tar +create +file=stooges larry moe curley
-@end example
+@command{tar} will print out a short message summarizing the operations and
+options to @command{tar} and exit. @xref{help}.
-If you specify a directory name as a file-name argument, @code{tar}
-will archive all the files in that directory. The following example
-creates an archive named @file{hail/hail/fredonia}, containing the
-contents of the directory @file{marx}:
+@opindex ignore-case, summary
+@item --ignore-case
+Ignore case when excluding files. @xref{controlling pattern-matching
+with exclude}.
-@example
-tar +create +file=hail/hail/fredonia marx
-@end example
+@opindex ignore-command-error, summary
+@item --ignore-command-error
+Ignore exit codes of subprocesses. @xref{Writing to an External Program}.
-If you don't specify files to put in the archive, @code{tar} archives
-all the files in the working directory. The following example creates
-an archive named @file{home} containing all the files in the working
-directory:
+@opindex ignore-failed-read, summary
+@item --ignore-failed-read
-@example
-tar +create +file=home
-@end example
+Do not exit unsuccessfully merely because an unreadable file was encountered.
+@xref{Reading}.
-@xref{File Name Lists}, for other ways to specify files to archive.
+@opindex ignore-zeros, summary
+@item --ignore-zeros
+@itemx -i
-Note: In the example above, an archive containing all the files in the
-working directory is being written to the working directory. GNU
-@code{tar} stores files in the working directory in an archive which
-is itself in the working directory without falling into an infinite
-loop. Other versions of @code{tar} may fall into this trap.
+With this option, @command{tar} will ignore zeroed blocks in the
+archive, which normally signals EOF. @xref{Reading}.
-@node Modifying, Listing Contents, Creating in Detail, Reading and Writing
-@section Modifying Archives
-@cindex Modifying archives
+@opindex incremental, summary
+@item --incremental
+@itemx -G
-Once an archive is created, you can add new archive members to it, add
-the contents of another archive, add newer versions of members already
-stored, or delete archive members already stored.
+Used to inform @command{tar} that it is working with an old
+@acronym{GNU}-format incremental backup archive. It is intended
+primarily for backwards compatibility only. @FIXME{incremental and
+listed-incremental}.
-To find out what files are already stored in an archive, use @samp{tar
-+list +file=@var{archive-name}}. @xref{Listing Contents}.
+@opindex index-file, summary
+@item --index-file=@var{file}
-@menu
-* Adding Files::
-* Appending Archives::
-* Deleting Archive Files:: Deleting Files From an Archive
-* Matching Format Parameters::
-@end menu
+Send verbose output to @var{file} instead of to standard output.
-@node Adding Files, Appending Archives, Modifying, Modifying
-@subsection Adding Files to an Archive
-@cindex Adding files to an archive
-@cindex Updating an archive
+@opindex info-script, summary
+@opindex new-volume-script, summary
+@item --info-script=@var{script-file}
+@itemx --new-volume-script=@var{script-file}
+@itemx -F @var{script-file}
-To add files to an archive, use @samp{tar +add-file}. The archive to
-be added to must already exist and be in proper archive format (which
-normally means it was created previously using @code{tar}). If the
-archive was created with a different block size than now specified,
-@code{tar} will report an error (@pxref{Blocking Factor}). If the
-archive is not a valid @code{tar} archive, the results will be
-unpredictable. You cannot add files to a compressed archive, however
-you can add files to the last volume of a multi-volume archive.
-@xref{Matching Format Parameters}.
-
-The following example adds the file @file{shemp} to the archive
-@file{stooges} created above:
-
-@example
-tar +add-file +file=stooges shemp
-@end example
-
-You must specify the files to be added; there is no default.
-
-@samp{tar +update} acts like @samp{tar +add-file}, but does not add
-files to the archive if there is already a file entry with that name
-in the archive that has the same modification time.
-
-Both @samp{+update} and @samp{+add-file} work by adding to the end of
-the archive. When you extract a file from the archive, only the
-version stored last will wind up in the file system. Because
-@samp{tar +extract} extracts files from an archive in sequence, and
-overwrites files with the same name in the file system, if a file name
-appears more than once in an archive the last version of the file will
-overwrite the previous versions which have just been extracted. You
-should avoid storing older versions of a file later in the archive.
-
-Note: @samp{+update} is not suitable for performing backups, because
-it doesn't change directory content entries, and because it lengthens
-the archive every time it is used.
-@c <<< xref to scripted backup, listed incremental, for info on backups.
-
-@node Appending Archives, Deleting Archive Files, Adding Files, Modifying
-@subsection Appending One Archive's Contents to Another Archive
-@cindex Adding archives to an archive
-@cindex Concatenating Archives
+When @command{tar} is performing multi-tape backups, @var{script-file} is run
+at the end of each tape. If @var{script-file} exits with nonzero status,
+@command{tar} fails immediately. @xref{info-script}, for a detailed
+discussion of @var{script-file}.
-To append copies of an archive or archives to the end of another
-archive, use @samp{tar +add-archive}. The source and target archives
-must already exist and have been created using compatable format
-parameters (@pxref{Matching Format Parameters}).
-
-@code{tar} will stop reading an archive if it encounters an
-end-of-archive marker. The @code{cat} utility does not remove
-end-of-archive markers, and is therefore unsuitable for concatenating
-archives. @samp{tar +add-archive} removes the end-of-archive marker
-from the target archive before each new archive is appended.
-@c <<< xref ignore-zeros
-
-You must specify the source archives using
-@samp{+file=@var{archive-name}} (@pxref{Archive Name}). If you do not
-specify the target archive , @code{tar} uses the value of the
-environment variable @code{TAPE}, or, if this has not been set, the
-default archive name.
-
-The following example adds the contents of the archive
-@file{hail/hail/fredonia} to the archive @file{stooges} (both archives
-were created in examples above):
-
-@example
-tar +add-archive +file=stooges hail/hail/fredonia
-@end example
-
-If you need to retrieve files from an archive that was added to using
-the @code{cat} utility, use the @samp{+ignore-zeros} option
-(@pxref{Archive Reading Options}).
-
-@node Deleting Archive Files, Matching Format Parameters, Appending Archives, Modifying
-@subsection Deleting Files From an Archive
-@cindex Deleting files from an archive
-@cindex Removing files from an archive
+@opindex interactive, summary
+@item --interactive
+@itemx --confirmation
+@itemx -w
-To delete archive members from an archive, use @samp{tar +delete}.
-You must specify the file names of the members to be deleted. All
-archive members with the specified file names will be removed from the
-archive.
+Specifies that @command{tar} should ask the user for confirmation before
+performing potentially destructive options, such as overwriting files.
+@xref{interactive}.
+
+@opindex keep-newer-files, summary
+@item --keep-newer-files
+
+Do not replace existing files that are newer than their archive copies
+when extracting files from an archive.
+
+@opindex keep-old-files, summary
+@item --keep-old-files
+@itemx -k
+
+Do not overwrite existing files when extracting files from an archive.
+@xref{Keep Old Files}.
+
+@opindex label, summary
+@item --label=@var{name}
+@itemx -V @var{name}
+
+When creating an archive, instructs @command{tar} to write @var{name}
+as a name record in the archive. When extracting or listing archives,
+@command{tar} will only operate on archives that have a label matching
+the pattern specified in @var{name}. @xref{Tape Files}.
+
+@opindex listed-incremental, summary
+@item --listed-incremental=@var{snapshot-file}
+@itemx -g @var{snapshot-file}
+
+During a @option{--create} operation, specifies that the archive that
+@command{tar} creates is a new @acronym{GNU}-format incremental
+backup, using @var{snapshot-file} to determine which files to backup.
+With other operations, informs @command{tar} that the archive is in
+incremental format. @FIXME{incremental and listed-incremental}.
+
+@opindex mode, summary
+@item --mode=@var{permissions}
+
+When adding files to an archive, @command{tar} will use
+@var{permissions} for the archive members, rather than the permissions
+from the files. The program @command{chmod} and this @command{tar}
+option share the same syntax for what @var{permissions} might be.
+@xref{File permissions, Permissions, File permissions, fileutils,
+@acronym{GNU} file utilities}. This reference also has useful
+information for those not being overly familiar with the Unix
+permission system.
+
+Of course, @var{permissions} might be plainly specified as an octal number.
+However, by using generic symbolic modifications to mode bits, this allows
+more flexibility. For example, the value @samp{a+rw} adds read and write
+permissions for everybody, while retaining executable bits on directories
+or on any other file already marked as executable.
+
+@opindex multi-volume, summary
+@item --multi-volume
+@itemx -M
-The following example removes the file @file{curley} from the archive
-@file{stooges}:
+Informs @command{tar} that it should create or otherwise operate on a
+multi-volume @command{tar} archive. @xref{Using Multiple Tapes}.
-@example
-tar +delete +file=stooges curley
-@end example
+@opindex new-volume-script, summary
+@item --new-volume-script
-You can only use @samp{tar +delete} on an archive if the archive
-device allows you to write to any point on the media.
+(see --info-script)
-@quotation
-@strong{Warning:} Don't try to delete an archive member from a
-magnetic tape, lest you scramble the archive. There is no safe way
-(except by completely re-writing the archive) to delete files from
-most kinds of magnetic tape.
-@end quotation
+@opindex seek, summary
+@item --seek
+@itemx -n
-@c <<< MIB -- how about automatic detection of archive media? give error
-@c <<< unless the archive device is either an ordinary file or different
-@c <<< input and output (+file=-).
+Assume that the archive media supports seeks to arbitrary
+locations. Usually @command{tar} determines automatically whether
+the archive can be seeked or not. This option is intended for use
+in cases when such recognition fails.
-@node Matching Format Parameters, , Deleting Archive Files, Modifying
-@subsection Matching the Format Parameters
+@opindex newer, summary
+@item --newer=@var{date}
+@itemx --after-date=@var{date}
+@itemx -N
-Some format parameters must be taken into consideration when modifying
-an archive:
+When creating an archive, @command{tar} will only add files that have changed
+since @var{date}. If @var{date} begins with @samp{/} or @samp{.}, it
+is taken to be the name of a file whose data modification time specifies
+the date. @xref{after}.
-Compressed archives cannot be modified.
+@opindex newer-mtime, summary
+@item --newer-mtime=@var{date}
-You have to specify the block size of the archive when modifying an
-archive with a non-default block size.
+Like @option{--newer}, but add only files whose
+contents have changed (as opposed to just @option{--newer}, which will
+also back up files for which any status information has changed).
-Multi-volume archives can be modified like any other archive. To add
-files to a multi-volume archive, you need to only mount the last
-volume of the archive media (and new volumes, if needed). For all
-other operations, you need to use the entire archive.
+@opindex no-anchored, summary
+@item --no-anchored
+An exclude pattern can match any subsequence of the name's components.
+@xref{controlling pattern-matching with exclude}.
-If a multi-volume archive was labeled using @samp{+label}
-(@pxref{Archive Label}) when it was created, @code{tar} will not
-automatically label volumes which are added later. To label
-subsequent volumes, specify @samp{+label=@var{archive-label}} again in
-conjunction with the @samp{+add-file}, @samp{+update} or
-@samp{+add-archive} operation.
-@cindex Labelling multi-volume archives
-@c <<< example
-
-@c <<< xref somewhere, for more information about format parameters.
-
-@node Listing Contents, Extracting From Archives, Modifying, Reading and Writing
-@section Listing the Contents of an Archive
-@cindex Names of the files in an archive
-@cindex Archive contents, list of
-@cindex Archive members, list of
-
-@samp{tar +list} prints a list of the file names of the archive
-members on the standard output. If you specify @var{file-name}
-arguments on the command line (or using the @samp{+files-from} option,
-@pxref{File Name Lists}), only the files you specify will be listed,
-and only if they exist in the archive. Files not specified will be
-ignored, unless they are under a specific directory.
-
-If you include the @samp{+verbose} option, @code{tar} prints an
-@samp{ls -l} type listing for the archive. @pxref{Additional
-Information}, for a description of the @samp{+verbose} option.
-
-If the blocking factor of the archive differs from the default,
-@code{tar} reports this. @xref{Blocking Factor}.
-
-@xref{Archive Reading Options} for a list of options which can be used
-to modify @samp{+list}'s operation.
-
-This example prints a list of the archive members of the archive
-@file{stooges}:
-
-@example
-tar +list +file=stooges
-@end example
-
-@noindent
-@code{tar} responds:
-
-@example
-larry
-moe
-shemp
-marx/julius
-marx/alexander
-marx/karl
-@end example
-
-This example generates a verbose list of the archive members of the
-archive file @file{dwarves}, which has a blocking factor of two:
-
-@example
-tar +list -v +file=blocks
-@end example
-
-@noindent
-@code{tar} responds:
-
-@example
-tar: Blocksize = 2 records
--rw------- ringo/user 42 May 1 13:29 1990 .bashful
--rw-rw-rw- ringo/user 42 Oct 4 13:29 1990 doc
--rw-rw-rw- ringo/user 42 Jul 20 18:01 1969 dopey
--rw-rw---- ringo/user 42 Nov 26 13:42 1963 grumpy
--rw-rw-rw- ringo/user 42 May 5 13:29 1990 happy
--rw-rw-rw- ringo/user 42 May 1 12:00 1868 sleepy
--rw-rw-rw- ringo/user 42 Jul 4 17:29 1776 sneezy
-@end example
-
-@node Extracting From Archives, , Listing Contents, Reading and Writing
-@section Extracting Files from an Archive
-@cindex Extraction
-@cindex Retrieving files from an archive
-@cindex Resurrecting files from an archive
+@opindex no-delay-directory-restore, summary
+@item --no-delay-directory-restore
-To read archive members from the archive and write them into the file
-system, use @samp{tar +extract}. The archive itself is left
-unchanged.
+Setting modification times and permissions of extracted
+directories when all files from this directory has been
+extracted. This is the default. @xref{Directory Modification Times and Permissions}.
-If you do not specify the files to extract, @code{tar} extracts all
-the files in the archive. If you specify the name of a directory as a
-file-name argument, @code{tar} will extract all files which have been
-stored as part of that directory. If a file was stored with a
-directory name as part of its file name, and that directory does not
-exist under the working directory when the file is extracted,
-@code{tar} will create the directory. @xref{Selecting Archive
-Members}, for information on specifying files to extract.
+@opindex no-ignore-case, summary
+@item --no-ignore-case
+Use case-sensitive matching when excluding files.
+@xref{controlling pattern-matching with exclude}.
-The following example shows the extraction of the archive
-@file{stooges} into an empty directory:
+@opindex no-ignore-command-error, summary
+@item --no-ignore-command-error
+Print warnings about subprocesses terminated with a non-zero exit
+code. @xref{Writing to an External Program}.
-@example
-tar +extract +file=stooges
-@end example
+@opindex no-quote-chars, summary
+@item --no-quote-chars=@var{string}
+Do not quote characters from @var{string}, even if the selected
+quoting style implies they should be quoted (@FIXME-pxref{Quoting Styles}).
-@noindent
-Generating a listing of the directory (@samp{ls}) produces:
+@opindex no-recursion, summary
+@item --no-recursion
-@example
-larry
-moe
-shemp
-marx
-@end example
+With this option, @command{tar} will not recurse into directories.
+@xref{recurse}.
-@noindent
-The subdirectory @file{marx} contains the files @file{julius},
-@file{alexander} and @file{karl}.
+@opindex no-same-owner, summary
+@item --no-same-owner
+@itemx -o
-If you wanted to just extract the files in the subdirectory
-@file{marx}, you could specify that directory as a file-name argument
-in conjunction with the @samp{+extract} operation:
+When extracting an archive, do not attempt to preserve the owner
+specified in the @command{tar} archive. This the default behavior
+for ordinary users.
-@example
-tar +extract +file=stooges marx
-@end example
+@opindex no-same-permissions, summary
+@item --no-same-permissions
-@quotation
-@strong{Warning:} Extraction can overwrite files in the file system.
-To avoid losing files in the file system when extracting files from
-the archive with the same name, use the @samp{+keep-old-files} option
-(@pxref{File Writing Options}).
-@end quotation
+When extracting an archive, subtract the user's umask from files from
+the permissions specified in the archive. This is the default behavior
+for ordinary users.
-If the archive was created using @samp{+block-size}, @samp{+compress}
-or @samp{+multi-volume}, you must specify those format options again
-when extracting files from the archive (@pxref{Format Variations}).
+@opindex no-wildcards, summary
+@item --no-wildcards
+Do not use wildcards when excluding files.
+@xref{controlling pattern-matching with exclude}.
-@menu
-* Archive Reading Options::
-* File Writing Options::
-* Scarce Disk Space:: Recovering From Scarce Disk Space
-@end menu
+@opindex no-wildcards-match-slash, summary
+@item --no-wildcards-match-slash
+Wildcards do not match @samp{/} when excluding files.
+@xref{controlling pattern-matching with exclude}.
-@node Archive Reading Options, File Writing Options, Extracting From Archives, Extracting From Archives
-@subsection Options to Help Read Archives
-@cindex Options when reading archives
-@cindex Reading incomplete blocks
-@cindex Blocks, incomplete
-@cindex End of archive markers, ignoring
-@cindex Ignoring end of archive markers
-@cindex Large lists of file names on small machines
-@cindex Small memory
-@cindex Running out of space
+@opindex null, summary
+@item --null
-@c <<< each option wants its own node. summary after menu
+When @command{tar} is using the @option{--files-from} option, this option
+instructs @command{tar} to expect filenames terminated with @option{NUL}, so
+@command{tar} can correctly work with file names that contain newlines.
+@xref{nul}.
-Normally, @code{tar} will request data in full block increments from
-an archive storage device. If the device cannot return a full block,
-@code{tar} will report an error. However, some devices do not always
-return full blocks, or do not require the last block of an archive to
-be padded out to the next block boundary. To keep reading until you
-obtain a full block, or to accept an incomplete block if it contains
-an end-of-archive marker, specify the @samp{+read-full-blocks} option
-in conjunction with the @samp{+extract} or @samp{+list} operations.
-@xref{Listing Contents}.
+@opindex numeric-owner, summary
+@item --numeric-owner
-The @samp{+read-full-blocks} option is turned on by default when
-@code{tar} reads an archive from standard input, or from a remote
-machine. This is because on BSD Unix systems, attempting to read a
-pipe returns however much happens to be in the pipe, even if it is
-less than was requested. If this option were not enabled, @code{tar}
-would fail as soon as it read an incomplete block from the pipe.
+This option will notify @command{tar} that it should use numeric user
+and group IDs when creating a @command{tar} file, rather than names.
+@xref{Attributes}.
-If you're not sure of the blocking factor of an archive, you can read
-the archive by specifying @samp{+read-full-blocks} and
-@samp{+block-size=@var{n}}, where @var{n} is a blocking factor larger
-than the blocking factor of the archive. This lets you avoid having
-to determine the blocking factor of an archive. @xref{Blocking
-Factor}.
+@item -o
+When extracting files, this option is a synonym for
+@option{--no-same-owner}, i.e. it prevents @command{tar} from
+restoring ownership of files being extracted.
-@table @samp
-@item +read-full-blocks
-@item -B
-Use in conjunction with @samp{tar +extract} to read an archive which
-contains incomplete blocks, or one which has a blocking factor less
-than the one specified.
-@end table
+When creating an archive, @option{-o} is a synonym for
+@option{--old-archive}. This behavior is for compatibility
+with previous versions of @GNUTAR{}, and will be
+removed in the future releases.
-Normally @code{tar} stops reading when it encounters a block of zeros
-between file entries (which usually indicates the end of the archive).
-@samp{+ignore-zeros} allows @code{tar} to completely read an archive
-which contains a block of zeros before the end (i.e.@: a damaged
-archive, or one which was created by @code{cat}-ing several archives
-together).
+@xref{Changes}, for more information.
-The @samp{+ignore-zeros} option is turned off by default because many
-versions of @code{tar} write garbage after the end of archive entry,
-since that part of the media is never supposed to be read. GNU
-@code{tar} does not write after the end of an archive, but seeks to
-maintain compatablity among archiving utilities.
+@opindex occurrence, summary
+@item --occurrence[=@var{number}]
-@table @samp
-@item +ignore-zeros
-@itemx -i
-To ignore blocks of zeros (ie.@: end-of-archive entries) which may be
-encountered while reading an archive. Use in conjunction with
-@samp{tar +extract} or @samp{tar +list}.
-@end table
+This option can be used in conjunction with one of the subcommands
+@option{--delete}, @option{--diff}, @option{--extract} or
+@option{--list} when a list of files is given either on the command
+line or via @option{-T} option.
-If you are using a machine with a small amount of memory, and you need
-to process large list of file-names, you can reduce the amount of
-space @code{tar} needs to process the list. To do so, specify the
-@samp{+same-order} option and provide an ordered list of file names.
-This option tells @code{tar} that the @file{file-name} arguments
-(provided on the command line, or read from a file using the
-@samp{+files-from} option) are listed in the same order as the files
-in the archive.
+This option instructs @command{tar} to process only the @var{number}th
+occurrence of each named file. @var{Number} defaults to 1, so
-You can create a file containing an ordered list of files in the
-archive by storing the output produced by @samp{tar +list
-+file=@var{archive-name}}. @xref{Listing Contents}, for information
-on the @samp{+list} operation.
+@smallexample
+tar -x -f archive.tar --occurrence filename
+@end smallexample
-This option is probably never needed on modern computer systems.
+@noindent
+will extract the first occurrence of @file{filename} from @file{archive.tar}
+and will terminate without scanning to the end of the archive.
-@table @samp
-@item +same-order
-@itemx +preserve-order
-@itemx -s
-To process large lists of file-names on machines with small amounts of
-memory. Use in conjunction with @samp{tar +compare}, @samp{tar +list}
-or @samp{tar +extract}.
-@end table
+@opindex old-archive, summary
+@item --old-archive
+Synonym for @option{--format=v7}.
-@c we don't need/want +preserve to exist any more
+@opindex one-file-system, summary
+@item --one-file-system
+@itemx -l
+Used when creating an archive. Prevents @command{tar} from recursing into
+directories that are on different file systems from the current
+directory.
+
+Earlier versions of @GNUTAR{} understood @option{-l} as a
+synonym for @option{--one-file-system}. Although such usage is still
+allowed in the present version, it is @emph{strongly discouraged}.
+The future versions of @GNUTAR{} will use @option{-l} as
+a synonym for @option{--check-links}.
+
+@xref{Changes}, for more information.
+
+@opindex overwrite, summary
+@item --overwrite
+
+Overwrite existing files and directory metadata when extracting files
+from an archive. @xref{Overwrite Old Files}.
+
+@opindex overwrite-dir, summary
+@item --overwrite-dir
+
+Overwrite the metadata of existing directories when extracting files
+from an archive. @xref{Overwrite Old Files}.
+
+@opindex owner, summary
+@item --owner=@var{user}
+
+Specifies that @command{tar} should use @var{user} as the owner of members
+when creating archives, instead of the user associated with the source
+file. @var{user} is first decoded as a user symbolic name, but if
+this interpretation fails, it has to be a decimal numeric user ID.
+@FIXME-xref{}
+
+There is no value indicating a missing number, and @samp{0} usually means
+@code{root}. Some people like to force @samp{0} as the value to offer in
+their distributions for the owner of files, because the @code{root} user is
+anonymous anyway, so that might as well be the owner of anonymous archives.
+
+This option does not affect extraction from archives.
+
+@opindex quote-chars, summary
+@item --quote-chars=@var{string}
+Always quote characters from @var{string}, even if the selected
+quoting style would not quote them (@FIXME-pxref{Quoting Styles}).
+
+@opindex quoting-style, summary
+@item --quoting-style=@var{style}
+Set quoting style to use when printing member and file names
+(@FIXME-pxref{Quoting Styles}). Valid @var{style} values are:
+@code{literal}, @code{shell}, @code{shell-always}, @code{c},
+@code{escape}, @code{locale}, and @code{clocale}. Default quoting
+style is @code{escape}, unless overridden while configuring the
+package.
+
+@opindex pax-option, summary
+@item --pax-option=@var{keyword-list}
+@FIXME{Such a detailed description does not belong there, move it elsewhere.}
+This option is meaningful only with @acronym{POSIX.1-2001} archives
+(@pxref{posix}). It modifies the way @command{tar} handles the
+extended header keywords. @var{Keyword-list} is a comma-separated
+list of keyword options, each keyword option taking one of
+the following forms:
+
+@table @asis
+@item delete=@var{pattern}
+When used with one of archive-creation commands,
+this option instructs @command{tar} to omit from extended header records
+that it produces any keywords matching the string @var{pattern}.
+
+When used in extract or list mode, this option instructs tar
+to ignore any keywords matching the given @var{pattern} in the extended
+header records. In both cases, matching is performed using the pattern
+matching notation described in @acronym{POSIX 1003.2}, 3.13
+(See @cite{glob(7)}). For example:
+
+@smallexample
+--pax-option delete=security.*
+@end smallexample
+
+would suppress security-related information.
+
+@item exthdr.name=@var{string}
+
+This keyword allows user control over the name that is written into the
+ustar header blocks for the extended headers. The name is obtained
+from @var{string} after substituting the following meta-characters:
+
+@multitable @columnfractions .30 .70
+@headitem Meta-character @tab Replaced By
+@item %d @tab The directory name of the file, equivalent to the
+result of the @command{dirname} utility on the translated pathname.
+@item %f @tab The filename of the file, equivalent to the result
+of the @command{basename} utility on the translated pathname.
+@item %p @tab The process ID of the @command{tar} process.
+@item %% @tab A @samp{%} character.
+@end multitable
+
+Any other @samp{%} characters in @var{string} produce undefined
+results.
+
+If no option @samp{exthdr.name=string} is specified, @command{tar}
+will use the following default value:
+
+@smallexample
+%d/PaxHeaders.%p/%f
+@end smallexample
+
+@item globexthdr.name=@var{string}
+This keyword allows user control over the name that is written into
+the ustar header blocks for global extended header records. The name
+shall will be obtained from the contents of @var{string}, after the
+following character substitutions have been made:
+
+@multitable @columnfractions .30 .70
+@headitem Meta-character @tab Replaced By
+@item %n @tab An integer that represents the
+sequence number of the global extended header record in the archive,
+starting at 1.
+@item %p @tab The process ID of the @command{tar} process.
+@item %% @tab A @samp{%} character.
+@end multitable
+
+Any other @samp{%} characters in string produce undefined results.
+
+If no option @samp{globexthdr.name=string} is specified, @command{tar}
+will use the following default value:
+
+@smallexample
+$TMPDIR/GlobalHead.%p.%n
+@end smallexample
-@node File Writing Options, Scarce Disk Space, Archive Reading Options, Extracting From Archives
-@subsection Changing How @code{tar} Writes Files
-@c <<< find a better title
-@cindex Overwriting old files, prevention
-@cindex Protecting old files
-@cindex Modification times of extracted files
-@cindex Permissions of extracted files
-@cindex Modes of extracted files
-@cindex Writing extracted files to standard output
-@cindex Standard output, writing extracted files to
+@noindent
+where @samp{$TMPDIR} represents the value of the @var{TMPDIR}
+environment variable. If @var{TMPDIR} is not set, @command{tar}
+uses @samp{/tmp}.
+
+@item @var{keyword}=@var{value}
+When used with one of archive-creation commands, these keyword/value pairs
+will be included at the beginning of the archive in a global extended
+header record. When used with one of archive-reading commands,
+@command{tar} will behave as if it has encountered these keyword/value
+pairs at the beginning of the archive in a global extended header
+record.
+
+@item @var{keyword}:=@var{value}
+When used with one of archive-creation commands, these keyword/value pairs
+will be included as records at the beginning of an extended header for
+each file. This is effectively equivalent to @var{keyword}=@var{value}
+form except that it creates no global extended header records.
+
+When used with one of archive-reading commands, @command{tar} will
+behave as if these keyword/value pairs were included as records at the
+end of each extended header; thus, they will override any global or
+file-specific extended header record keywords of the same names.
+For example, in the command:
+
+@smallexample
+tar --format=posix --create \
+ --file archive --pax-option gname:=user .
+@end smallexample
+
+the group name will be forced to a new value for all files
+stored in the archive.
+@end table
-Normally, @code{tar} writes extracted files into the file system
-without regard to the files already on the system---files with the
-same name as archive members are overwritten. To prevent @code{tar}
-from extracting an archive member from an archive, if doing so will
-overwrite a file in the file system, use @samp{+keep-old-files} in
-conjunction with the @samp{+extract} operation. When this option is
-specified, @code{tar} reports an error stating the name of the files
-in conflict, instead of writing the file from the archive.
+@opindex portability, summary
+@item --portability
+@itemx --old-archive
+Synonym for @option{--format=v7}.
-@table @samp
-@item +keep-old files
-@itemx -k
-Prevents @code{tar} from overwriting files in the file system during
-extraction.
-@end table
+@opindex posix, summary
+@item --posix
+Same as @option{--format=posix}.
-Normally, @code{tar} sets the modification times of extracted files to
-the modification times recorded for the files in the archive, but
-limits the permissions of extracted files by the current @code{umask}
-setting.
+@opindex preserve, summary
+@item --preserve
-To set the modification times of extracted files to the time when
-the files were extracted, use the @samp{+modification-time} option in
-conjunction with @samp{tar +extract}.
+Synonymous with specifying both @option{--preserve-permissions} and
+@option{--same-order}. @xref{Setting Access Permissions}.
-@table @samp
-@item +modification-time
-@itemx -m
-Sets the modification time of extracted archive members to the time
-they were extracted, not the time recorded for them in the archive.
-Use in conjunction with @samp{+extract}.
-@end table
+@opindex preserve-order, summary
+@item --preserve-order
-To set the modes (access permissions) of extracted files to those
-recorded for those files in the archive, use the
-@samp{+preserve-permissions} option in conjunction with the
-@samp{+extract} operation.
-@c <<<mib --- should be aliased to ignore-umask.
+(See @option{--same-order}; @pxref{Reading}.)
-@table @samp
-@item +preserve-permission
-@itemx +same-permission
-@itemx +ignore-umask
+@opindex preserve-permissions, summary
+@opindex same-permissions, summary
+@item --preserve-permissions
+@itemx --same-permissions
@itemx -p
-Set modes of extracted archive members to those recorded in the
-archive, instead of current umask settings. Use in conjunction with
-@samp{+extract}.
-@end table
-@c <<< following paragraph needs to be rewritten:
-@c <<< why doesnt' this cat files together, why is this useful. is it
-@c <<< really useful with more than one file?
-To write the files extracted to the standard output, instead of
-creating the files on the file system, use @samp{+to-stdout} in
-conjunction with @samp{tar +extract}. This option is useful if you
-are extracting files to send them through a pipe, and do not need to
-preserve them in the file system.
+When @command{tar} is extracting an archive, it normally subtracts the
+users' umask from the permissions specified in the archive and uses
+that number as the permissions to create the destination file.
+Specifying this option instructs @command{tar} that it should use the
+permissions directly from the archive. @xref{Setting Access Permissions}.
-@table @samp
-@item +to-stdout
-@itemx -O
-Writes files to the standard output. Used in conjunction with
-@samp{+extract}.
-@end table
+@opindex read-full-records, summary
+@item --read-full-records
+@itemx -B
-@c <<< why would you want to do such a thing, how are files separated on
-@c <<< the standard output? is this useful with more that one file? are
-@c <<< pipes the real reason?
+Specifies that @command{tar} should reblock its input, for reading
+from pipes on systems with buggy implementations. @xref{Reading}.
-@node Scarce Disk Space, , File Writing Options, Extracting From Archives
-@subsection Recovering From Scarce Disk Space
-@cindex Middle of the archive, starting in the
-@cindex Running out of space during extraction
-@cindex Disk space, running out of
-@cindex Space on the disk, recovering from lack of
+@opindex record-size, summary
+@item --record-size=@var{size}
-If a previous attempt to extract files failed due to lack of disk
-space, you can use @samp{+starting-file=@var{file-name}} to start
-extracting only after file @var{file-name} when extracting files from
-the archive. This assumes, of course, that there is now free space,
-or that you are now extracting into a different file system.
+Instructs @command{tar} to use @var{size} bytes per record when accessing the
+archive. @xref{Blocking Factor}.
-@table @samp
-@item +starting-file=@var{file-name}
-@itemx -K @var{file-name}
-Starts an operation in the middle of an archive. Use in conjunction
-with @samp{+extract} or @samp{+list}.
-@end table
+@opindex recursion, summary
+@item --recursion
-If you notice you are running out of disk space during an extraction
-operation, you can also suspend @code{tar}, remove unnecessary files
-from the file system, and then restart the same @code{tar} operation.
-In this case, @samp{+starting-file} is not necessary.
+With this option, @command{tar} recurses into directories.
+@xref{recurse}.
-@c <<< xref incremental, xref +interactive, xref +exclude
+@opindex recursive-unlink, summary
+@item --recursive-unlink
-@node Insuring Accuracy, Selecting Archive Members, Reading and Writing, Top
-@chapter Insuring the Accuracy of an Archive
+Remove existing
+directory hierarchies before extracting directories of the same name
+from the archive. @xref{Recursive Unlink}.
-You can insure the accuracy of an archive by comparing files in the
-system with archive members. @code{tar} can compare an archive to the
-file system as the archive is being written, to verify a write
-operation, or can compare a previously written archive, to insure that
-it is up to date.
+@opindex remove-files, summary
+@item --remove-files
-@menu
-* Write Verification::
-* Comparing::
-@end menu
+Directs @command{tar} to remove the source file from the file system after
+appending it to an archive. @xref{remove files}.
-@node Write Verification, Comparing, Insuring Accuracy, Insuring Accuracy
-@section Verifying Data as It is Stored
-@cindex Verifying a write operation
-@cindex Double-checking a write operation
+@opindex restrict, summary
+@item --restrict
-To check for discrepancies in an archive immediately after it is
-written, use the @samp{+verify} option in conjunction with the
-@samp{tar +create} operation. When this option is specified,
-@code{tar} checks archive members against their counterparts in the file
-system, and reports discrepancies on the standard error. In
-multi-volume archives, each volume is verified after it is written,
-before the next volume is written.
+Disable use of some potentially harmful @command{tar} options.
+Currently this option disables shell invocaton from multi-volume menu
+(@pxref{Using Multiple Tapes}).
-To verify an archive, you must be able to read it from before the end
-of the last written entry. This option is useful for detecting data
-errors on some tapes. Archives written to pipes, some cartridge tape
-drives, and some other devices cannot be verified.
+@opindex rmt-command, summary
+@item --rmt-command=@var{cmd}
-@table @samp
-@item +verify
-@itemx -W
-Checks for discrepancies in the archive immediately after it is
-written. Use in conjunction with @samp{tar +create}.
-@end table
+Notifies @command{tar} that it should use @var{cmd} instead of
+the default @file{/usr/libexec/rmt} (@pxref{Remote Tape Server}).
-@node Comparing, , Write Verification, Insuring Accuracy
-@section Comparing an Archive with the File System
-@cindex Verifying the currency of an archive
+@opindex rsh-command, summary
+@item --rsh-command=@var{cmd}
-@samp{tar +compare} compares archive members in an existing archive
-with their counterparts in the file system, and reports differences in
-file size, mode, owner, modification date and contents. If a file is
-represented in the archive but does not exist in the file system,
-@code{tar} reports a difference.
-
-If you use @var{file-name} arguments in conjunction with @samp{tar
-+compare}, @code{tar} compares the archived versions of the files
-specified with their counterparts in the file system. If you specify
-a file that is not in the archive, @code{tar} will report an error. If
-you don't specify any files, @code{tar} compares all the files in the
-archive.
+Notifies @command{tar} that is should use @var{cmd} to communicate with remote
+devices. @xref{Device}.
-Because @code{tar} only checks files in the archive against files in
-the file system, and not vice versa, it ignores files in the file
-system that do not exist in the archive.
+@opindex same-order, summary
+@item --same-order
+@itemx --preserve-order
+@itemx -s
-The following example compares the archive members @file{larry},
-@file{moe} and @file{curly} in the archive @file{stooges} with files
-of the same name in the file system.
+This option is an optimization for @command{tar} when running on machines with
+small amounts of memory. It informs @command{tar} that the list of file
+arguments has already been sorted to match the order of files in the
+archive. @xref{Reading}.
-@example
-tar +compare +file=stooges larry moe curly
-@end example
+@opindex same-owner, summary
+@item --same-owner
-@noindent
-If a file, for example @file{curly}, did not exist in the archive,
-@code{tar} would report an error, as follows:
+When extracting an archive, @command{tar} will attempt to preserve the owner
+specified in the @command{tar} archive with this option present.
+This is the default behavior for the superuser; this option has an
+effect only for ordinary users. @xref{Attributes}.
-@example
-curly: does not exist
-@end example
+@opindex same-permissions, summary
+@item --same-permissions
-@node Selecting Archive Members, User Interaction, Insuring Accuracy, Top
-@chapter Selecting Archive Members
-@cindex Specifying files to act on
-@cindex Specifying archive members
+(See @option{--preserve-permissions}; @pxref{Setting Access Permissions}.)
-@dfn{File-name arguments} specify which files in the file system
-@code{tar} operates on, when creating or adding to an archive, or
-which archive members @code{tar} operates on, when reading or
-deleting from an archive. (@pxref{Reading and Writing}.)
+@opindex show-defaults, summary
+@item --show-defaults
-To specify file names, you can include them as the last arguments on
-the command line, as follows:
-@example
-tar @var{operation} [@var{option1} @var{option2} ..] [@var{file-name-1} @var{file-name-2} ...]
-@end example
+Displays the default options used by @command{tar} and exits
+successfully. This option is intended for use in shell scripts.
+Here is an example of what you can see using this option:
-If you specify a directory name as a file name argument, all the files
-in that directory are operated on by @code{tar}.
+@smallexample
+$ tar --show-defaults
+--format=gnu -f- -b20 --quoting-style=escape \
+--rmt-command=/usr/libexec/rmt --rsh-command=/usr/bin/rsh
+@end smallexample
-If you do not specify files when @code{tar} is invoked, @code{tar}
-operates on all the non-directory files in the working directory (if
-the operation is @samp{+create}), all the archive members in the
-archive (if a read operation is specified), or does nothing (if any
-other operation is specified).
+@opindex show-omitted-dirs, summary
+@item --show-omitted-dirs
-@menu
-* File Name Lists:: Reading File Names from a File
-* File Name Interpretation:: this needs a better title
-* File Exclusion:: so does this
-@end menu
+Instructs @command{tar} to mention directories its skipping over when
+operating on a @command{tar} archive. @xref{show-omitted-dirs}.
-@node File Name Lists, File Name Interpretation, Selecting Archive Members, Selecting Archive Members
-@section Reading a List of File Names from a File
-@cindex Lists of file names
-@cindex File-name arguments, alternatives
+@opindex show-stored-names, summary
+@item --show-stored-names
-To read file names from a file on the file system, instead of from the
-command line, use the @samp{+files-from=@var{file}} option. If you
-specify @samp{-} as @var{file}, the file names are read from standard
-input. Note that using both @samp{+files-from=-} and @samp{+file=-}
-in the same command will not work unless the operation is
-@samp{+create}. @xref{Archive Name}, for an explanation of the
-@samp{+file} option.
+This option has effect only when used in conjunction with one of
+archive creation operations. It instructs tar to list the member names
+stored in the archive, as opposed to the actual file
+names. @xref{listing member and file names}.
-@table @samp
-@item +files-from=@var{file}
-@itemx -T @var{file}
-Reads file-name arguments from a file on the file system, instead of
-from the command line. Use in conjunction with any operation.
-@end table
+@opindex sparse, summary
+@item --sparse
+@itemx -S
-@node File Name Interpretation, File Exclusion, File Name Lists, Selecting Archive Members
-@section File Name Interpretation
-@cindex File Names, interpreting
+Invokes a @acronym{GNU} extension when adding files to an archive that handles
+sparse files efficiently. @xref{sparse}.
-@c <<<<add some text -ringo
+@opindex starting-file, summary
+@item --starting-file=@var{name}
+@itemx -K @var{name}
-@menu
-* Absolute File Names::
-* Changing Working Directory::
-* Archiving with Symbolic Links:: Archiving Using Symbolic Links
-@end menu
+This option affects extraction only; @command{tar} will skip extracting
+files in the archive until it finds one that matches @var{name}.
+@xref{Scarce}.
-@node Absolute File Names, Changing Working Directory, File Name Interpretation, File Name Interpretation
-@subsection Storing and Extracting Files Relative to Root
+@opindex strip-components, summary
+@item --strip-components=@var{number}
+Strip given @var{number} of leading components from file names before
+extraction.@footnote{This option was called @option{--strip-path} in
+version 1.14.} For example, if archive @file{archive.tar} contained
+@file{/some/file/name}, then running
-@c <<< is this what this does, or does it just preserve the slash?
-@c <<< is it still called +absolute-paths?
+@smallexample
+tar --extract --file archive.tar --strip-components=2
+@end smallexample
-@c To archive or extract files relative to the root directory, specify
-@c the @samp{+absolute-paths} option.
+@noindent
+would extracted this file to file @file{name}.
-@c Normally, @code{tar} acts on files relative to the working
-@c directory---ignoring superior directory names when archiving, and
-@c ignoring leading slashes when extracting.
+@opindex suffix, summary
+@item --suffix=@var{suffix}
-@c When you specify @samp{+absolute-paths}, @code{tar} stores file names
-@c including all superior directory names, and preserves leading slashes.
-@c If you only invoked @code{tar} from the root directory you would never
-@c need the @samp{+absolute-paths} option, but using this option may be
-@c more convenient than switching to root.
+Alters the suffix @command{tar} uses when backing up files from the default
+@samp{~}. @xref{backup}.
-@c >>> should be an example in the tutorial/wizardry section using this
-@c >>> to transfer files between systems.
+@opindex tape-length, summary
+@item --tape-length=@var{num}
+@itemx -L @var{num}
-@c >>> is write access an issue?
+Specifies the length of tapes that @command{tar} is writing as being
+@w{@var{num} x 1024} bytes long. @xref{Using Multiple Tapes}.
-@table @samp
-@item +absolute-paths
-Preserves full file names (inclusing superior dirctory names) when
-archiving files. Preserves leading slash when extracting files.
-@end table
+@opindex test-label, summary
+@item --test-label
-@node Changing Working Directory, Archiving with Symbolic Links, Absolute File Names, File Name Interpretation
-@subsection Changing the Working Directory Within a List of File-names
-@cindex Directory, changing in mid-stream
-@cindex Working directory, specifying
+Reads the volume label. If an argument is specified, test whether it
+matches the volume label. @xref{--test-label option}.
-To change working directory in the middle of a list of file names,
-(either on the command line or in a file specified using
-@samp{+files-from}), use @samp{+directory=@var{directory}}. This will
-change the working directory to the directory @var{directory} after
-that point in the list. For example,
+@opindex to-command, summary
+@item --to-command=@var{command}
-@example
-tar +create iggy ziggy +directory=baz melvin
-@end example
+During extraction @command{tar} will pipe extracted files to the
+standard input of @var{command}. @xref{Writing to an External Program}.
-@noindent
-will place the files @file{iggy} and @file{ziggy} from the current
-directory into the archive, followed by the file @file{melvin} from
-the directory @file{baz}. This option is especially useful when you
-have several widely separated files that you want to store in the same
-directory in the archive.
+@opindex to-stdout, summary
+@item --to-stdout
+@itemx -O
-Note that the file @file{melvin} is recorded in the archive under the
-precise name @file{melvin}, @emph{not} @file{baz/melvin}. Thus, the
-archive will contain three files that all appear to have come from the
-same directory; if the archive is extracted with plain @samp{tar
-+extract}, all three files will be written in the current directory.
+During extraction, @command{tar} will extract files to stdout rather
+than to the file system. @xref{Writing to Standard Output}.
-Contrast this with the command
+@opindex totals, summary
+@item --totals
-@example
-tar -c iggy ziggy bar/melvin
-@end example
+Displays the total number of bytes written after creating an archive.
+@xref{verbose}.
-@noindent
-which records the third file in the archive under the name
-@file{bar/melvin} so that, if the archive is extracted using @samp{tar
-+extract}, the third file will be written in a subdirectory named
-@file{bar}.
+@opindex touch, summary
+@item --touch
+@itemx -m
-@table @samp
-@item +directory=@file{directory}
-@itemx -C @file{directory}
-Changes the working directory.
-@end table
+Sets the data modification time of extracted files to the extraction time,
+rather than the data modification time stored in the archive.
+@xref{Data Modification Times}.
-@c <<<need to test how extract deals with this, and add an example -ringo
+@opindex uncompress, summary
+@item --uncompress
-@node Archiving with Symbolic Links, , Changing Working Directory, File Name Interpretation
-@subsection Archiving Using Symbolic Links
-@cindex File names, using symbolic links
-@cindex Symbolic link as file name
+(See @option{--compress}. @pxref{gzip})
-@samp{+dereference} is used with @samp{tar +create}, and causes
-@code{tar} to archive files which are referenced by a symbolic link,
-using the name of the link as the file name.
+@opindex ungzip, summary
+@item --ungzip
-<<<this needs to be checked by MIB and then re-written, with an example
-The name under which the file is stored in the file system is not
-recorded in the archive. To record both the symbolic link name and
-the file name in the system, archive the file under both names. If
-all links were recorded automatically by @code{tar}, an extracted file
-might be linked to a file name that no longer exists in the file
-system.
+(See @option{--gzip}. @pxref{gzip})
-@c <<< is the following still true? - ringo
-If a linked-to file is encountered again by @code{tar} while creating
-the same archive, an entire second copy of it will be stored. This
-could be considered a bug.
+@opindex unlink-first, summary
+@item --unlink-first
+@itemx -U
-@table @samp
-@item +dereference
-@itemx -h
-Stores files referenced by a symbolic link, using the name of the link
-as the file name. Use in conjunction with any write operation.
-@end table
+Directs @command{tar} to remove the corresponding file from the file
+system before extracting it from the archive. @xref{Unlink First}.
-@node File Exclusion, , File Name Interpretation, Selecting Archive Members
-@section Selecting Files by Characteristic
-@cindex File names, excluding files by
-@cindex Excluding files by name and pattern
-@cindex Excluding files by file system
-@cindex File system boundaries, not crossing
-@cindex Excluding file by age
-@cindex Modification time, excluding files by
-@cindex Age, excluding files by
+@opindex use-compress-program, summary
+@item --use-compress-program=@var{prog}
-To avoid crossing file system boundaries when archiving parts of a
-directory tree, use @samp{+one-file-system}. This option only affects
-files that are archived because they are in a directory that is being
-archived; files explicitly named on the command line are archived
-regardless of where they reside.
+Instructs @command{tar} to access the archive through @var{prog}, which is
+presumed to be a compression program of some sort. @xref{gzip}.
-This option is useful for making full or incremental archival backups
-of a file system.
+@opindex utc, summary
+@item --utc
-If this option is used in conjunction with @samp{+verbose}, files that
-are excluded are mentioned by name on the standard error.
+Display file modification dates in @acronym{UTC}. This option implies
+@option{--verbose}.
-@table @samp
-@item +one-file-system
-@itemx -l
-Prevents @code{tar} from crossing file system boundaries when
-archiving. Use in conjunction with any write operation.
-@end table
+@opindex verbose, summary
+@item --verbose
+@itemx -v
-To avoid operating on files whose names match a particular pattern,
-use the @samp{+exclude=@var{pattern}} or
-@samp{+exclude-from=@var{file}} options.
+Specifies that @command{tar} should be more verbose about the operations its
+performing. This option can be specified multiple times for some
+operations to increase the amount of information displayed.
+@xref{verbose}.
-When you specify the @samp{+exclude=@var{pattern}} option, @code{tar}
-ignores files which match the @var{pattern}, which can be a single
-file name or a more complex expression. Thus, if you invoke
-@code{tar} with @samp{tar +create +exclude=*.o}, no files whose names
-end in @file{.o} are included in the archive.
-@c <<< what other things can you use besides "*"?
+@opindex verify, summary
+@item --verify
+@itemx -W
-@samp{+exclude-from=@var{file}} acts like @samp{+exclude}, but
-specifies a file @var{file} containing a list of patterns. @code{tar}
-ignores files with names that fit any of these patterns.
+Verifies that the archive was correctly written when creating an
+archive. @xref{verify}.
-You can use either option more than once in a single command.
+@opindex version, summary
+@item --version
-@table @samp
-@item +exclude=@var{pattern}
-Causes @code{tar} to ignore files that match the @var{pattern}.
+Print information about the program's name, version, origin and legal
+status, all on standard output, and then exit successfully.
+@xref{help}.
-@item +exclude-from=@var{file}
-Causes @code{tar} to ignore files that match the patterns listed in
-@var{file}.
-@end table
-@c +exclude-from used to be "+exclude", +exclude didn't used to exist.
+@opindex volno-file, summary
+@item --volno-file=@var{file}
-To operate only on files with modification or status-change times
-after a particular date, use @samp{+after-date=@var{date}}. You can
-use this option with @samp{tar +create} or @samp{tar +add-file} to
-insure only new files are archived, or with @samp{tar +extract} to
-insure only recent files are resurrected. @refill
-@c +after-date @var{date} or +newer @var{date}
+Used in conjunction with @option{--multi-volume}. @command{tar} will keep track
+of which volume of a multi-volume archive its working in @var{file}.
+@xref{volno-file}.
-@samp{+newer-mtime=@var{date}} acts like @samp{+after-date=@var{date}},
-but tests just the modification times of the files, ignoring
-status-change times.
+@opindex wildcards, summary
+@item --wildcards
+Use wildcards when excluding files.
+@xref{controlling pattern-matching with exclude}.
-@c <<<need example of +newer-mtime with quoted argument
-Remember that the entire date argument should be quoted if it contains
-any spaces.
+@opindex wildcards-match-slash, summary
+@item --wildcards-match-slash
+Wildcards match @samp{/} when excluding files.
+@xref{controlling pattern-matching with exclude}.
+@end table
+@node Short Option Summary
+@subsection Short Options Cross Reference
-@strong{Please Note:} @samp{+after-date} and @samp{+newer-mtime}
-should not be used for incremental backups. Some files (such as those
-in renamed directories) are not selected up properly by these options.
-@c xref to incremental backup chapter when node name is decided.
+Here is an alphabetized list of all of the short option forms, matching
+them with the equivalent long option.
-@table @samp
-@item +after-date=@var{date}
-@itemx +newer=@var{date}
-@itemx -N @var{date}
-Acts on files only if their modification or inode-changed times are
-later than @var{date}. Use in conjunction with any operation.
-@item +newer-mtime=@var{date}
-Acts like @samp{+after-date}, but only looks at modification times.
-@end table
+@table @option
-@c <<< following is the getdate date format --- needs to be re-written,
-@c <<< made a sub-node:
+@item -A
-Time/Date Formats Accepted by getdate
-(omitting obscure constructions)
+@option{--concatenate}
-The input consists of one or more of: time zone day date year
-in any order.
+@item -B
-Those in turn consist of (`|' and `/' mean `or', `[]' means `optional'):
+@option{--read-full-records}
-time: H am/pm | H:M [am/pm] | H:M:S [am/pm]
-zone: timezone-name | timezone-name dst
-day: day-name | day-name, | N day-name
-date: M/D | M/D/Y | month-name D | month-name D, Y | D month-name | D month-name Y
-year: Y
+@item -C
-am can also be a.m., pm can also be p.m.
-case and spaces around punctuation are not significant.
-month and day names can be abbreviated. >>>
+@option{--directory}
-@node User Interaction, Backups and Restoration, Selecting Archive Members, Top
-@chapter User Interaction
-@cindex Getting more information during the operation
-@cindex Information during operation
-@cindex Feedback from @code{tar}
+@item -F
-Once you have typed a @code{tar}command, it is usually performed
-without any further information required of the user, or provided by
-@code{tar}. The following options allow you to generate progress and
-status information during an operation, or to confirm operations on
-files as they are performed.
+@option{--info-script}
+
+@item -G
+
+@option{--incremental}
+
+@item -K
+
+@option{--starting-file}
+
+@item -L
+
+@option{--tape-length}
+
+@item -M
+
+@option{--multi-volume}
+
+@item -N
+
+@option{--newer}
+
+@item -O
+
+@option{--to-stdout}
+
+@item -P
+
+@option{--absolute-names}
+
+@item -R
+
+@option{--block-number}
+
+@item -S
+
+@option{--sparse}
+
+@item -T
+
+@option{--files-from}
+
+@item -U
+
+@option{--unlink-first}
+
+@item -V
+
+@option{--label}
+
+@item -W
+
+@option{--verify}
+
+@item -X
+
+@option{--exclude-from}
+
+@item -Z
+
+@option{--compress}
+
+@item -b
+
+@option{--blocking-factor}
+
+@item -c
+
+@option{--create}
+
+@item -d
+
+@option{--compare}
+
+@item -f
+
+@option{--file}
+
+@item -g
+
+@option{--listed-incremental}
+
+@item -h
+
+@option{--dereference}
+
+@item -i
+
+@option{--ignore-zeros}
+
+@item -j
+
+@option{--bzip2}
+
+@item -k
+
+@option{--keep-old-files}
+
+@item -l
+
+@option{--one-file-system}. Use of this short option is deprecated. It
+is retained for compatibility with the earlier versions of GNU
+@command{tar}, and will be changed in future releases.
+
+@xref{Changes}, for more information.
+
+@item -m
+
+@option{--touch}
+
+@item -o
+
+When creating --- @option{--no-same-owner}, when extracting ---
+@option{--portability}.
+
+The later usage is deprecated. It is retained for compatibility with
+the earlier versions of @GNUTAR{}. In the future releases
+@option{-o} will be equivalent to @option{--no-same-owner} only.
+
+@item -p
+
+@option{--preserve-permissions}
+
+@item -r
+
+@option{--append}
+
+@item -s
+
+@option{--same-order}
+
+@item -t
+
+@option{--list}
+
+@item -u
+
+@option{--update}
+
+@item -v
+
+@option{--verbose}
+
+@item -w
+
+@option{--interactive}
+
+@item -x
+
+@option{--extract}
+
+@item -z
+
+@option{--gzip}
+
+@end table
+
+@node help
+@section @GNUTAR{} documentation
+
+@cindex Getting program version number
+@opindex version
+@cindex Version of the @command{tar} program
+Being careful, the first thing is really checking that you are using
+@GNUTAR{}, indeed. The @option{--version} option
+causes @command{tar} to print information about its name, version,
+origin and legal status, all on standard output, and then exit
+successfully. For example, @w{@samp{tar --version}} might print:
+
+@smallexample
+tar (GNU tar) 1.15.2
+Copyright (C) 2006 Free Software Foundation, Inc.
+This is free software. You may redistribute copies of it under the terms of
+the GNU General Public License <http://www.gnu.org/licenses/gpl.html>.
+There is NO WARRANTY, to the extent permitted by law.
+
+Written by John Gilmore and Jay Fenlason.
+@end smallexample
+
+@noindent
+The first occurrence of @samp{tar} in the result above is the program
+name in the package (for example, @command{rmt} is another program),
+while the second occurrence of @samp{tar} is the name of the package
+itself, containing possibly many programs. The package is currently
+named @samp{tar}, after the name of the main program it
+contains@footnote{There are plans to merge the @command{cpio} and
+@command{tar} packages into a single one which would be called
+@code{paxutils}. So, who knows if, one of this days, the
+@option{--version} would not output @w{@samp{tar (@acronym{GNU}
+paxutils) 3.2}}}.
+
+@cindex Obtaining help
+@cindex Listing all @command{tar} options
+@opindex help, introduction
+Another thing you might want to do is checking the spelling or meaning
+of some particular @command{tar} option, without resorting to this
+manual, for once you have carefully read it. @GNUTAR{}
+has a short help feature, triggerable through the
+@option{--help} option. By using this option, @command{tar} will
+print a usage message listing all available options on standard
+output, then exit successfully, without doing anything else and
+ignoring all other options. Even if this is only a brief summary, it
+may be several screens long. So, if you are not using some kind of
+scrollable window, you might prefer to use something like:
+
+@smallexample
+$ @kbd{tar --help | less}
+@end smallexample
+
+@noindent
+presuming, here, that you like using @command{less} for a pager. Other
+popular pagers are @command{more} and @command{pg}. If you know about some
+@var{keyword} which interests you and do not want to read all the
+@option{--help} output, another common idiom is doing:
+
+@smallexample
+tar --help | grep @var{keyword}
+@end smallexample
+
+@noindent
+for getting only the pertinent lines. Notice, however, that some
+@command{tar} options have long description lines and the above
+command will list only the first of them.
+
+The exact look of the option summary displayed by @kbd{tar --help} is
+configurable. @xref{Configuring Help Summary}, for a detailed description.
+
+@opindex usage
+If you only wish to check the spelling of an option, running @kbd{tar
+--usage} may be a better choice. This will display a terse list of
+@command{tar} option without accompanying explanations.
+
+The short help output is quite succinct, and you might have to get
+back to the full documentation for precise points. If you are reading
+this paragraph, you already have the @command{tar} manual in some
+form. This manual is available in a variety of forms from
+@url{http://www.gnu.org/software/tar/manual}. It may printed out of the @GNUTAR{}
+distribution, provided you have @TeX{} already installed somewhere,
+and a laser printer around. Just configure the distribution, execute
+the command @w{@samp{make dvi}}, then print @file{doc/tar.dvi} the
+usual way (contact your local guru to know how). If @GNUTAR{}
+has been conveniently installed at your place, this
+manual is also available in interactive, hypertextual form as an Info
+file. Just call @w{@samp{info tar}} or, if you do not have the
+@command{info} program handy, use the Info reader provided within
+@acronym{GNU} Emacs, calling @samp{tar} from the main Info menu.
+
+There is currently no @code{man} page for @GNUTAR{}.
+If you observe such a @code{man} page on the system you are running,
+either it does not belong to @GNUTAR{}, or it has not
+been produced by @acronym{GNU}. Some package maintainers convert
+@kbd{tar --help} output to a man page, using @command{help2man}. In
+any case, please bear in mind that the authoritative source of
+information about @GNUTAR{} is this Texinfo documentation.
+
+@node defaults
+@section Obtaining @GNUTAR{} default values
+
+@opindex show-defaults
+@GNUTAR{} has some predefined defaults that are used when you do not
+explicitely specify another values. To obtain a list of such
+defaults, use @option{--show-defaults} option. This will output the
+values in the form of @command{tar} command line options:
+
+@smallexample
+@group
+@kbd{tar --show-defaults}
+--format=gnu -f- -b20 --rmt-command=/etc/rmt --rsh-command=/usr/bin/rsh
+@end group
+@end smallexample
+
+@noindent
+The above output shows that this version of @GNUTAR{} defaults to
+using @samp{gnu} archive format (@pxref{Formats}), it uses standard
+output as the archive, if no @option{--file} option has been given
+(@pxref{file tutorial}), the default blocking factor is 20
+(@pxref{Blocking Factor}). It also shows the default locations where
+@command{tar} will look for @command{rmt} and @command{rsh} binaries.
+
+@node verbose
+@section Checking @command{tar} progress
+
+Typically, @command{tar} performs most operations without reporting any
+information to the user except error messages. When using @command{tar}
+with many options, particularly ones with complicated or
+difficult-to-predict behavior, it is possible to make serious mistakes.
+@command{tar} provides several options that make observing @command{tar}
+easier. These options cause @command{tar} to print information as it
+progresses in its job, and you might want to use them just for being
+more careful about what is going on, or merely for entertaining
+yourself. If you have encountered a problem when operating on an
+archive, however, you may need more information than just an error
+message in order to solve the problem. The following options can be
+helpful diagnostic tools.
+
+@cindex Verbose operation
+@opindex verbose
+Normally, the @option{--list} (@option{-t}) command to list an archive
+prints just the file names (one per line) and the other commands are
+silent. When used with most operations, the @option{--verbose}
+(@option{-v}) option causes @command{tar} to print the name of each
+file or archive member as it is processed. This and the other options
+which make @command{tar} print status information can be useful in
+monitoring @command{tar}.
+
+With @option{--create} or @option{--extract}, @option{--verbose} used
+once just prints the names of the files or members as they are processed.
+Using it twice causes @command{tar} to print a longer listing
+(reminiscent of @samp{ls -l}) for each member. Since @option{--list}
+already prints the names of the members, @option{--verbose} used once
+with @option{--list} causes @command{tar} to print an @samp{ls -l}
+type listing of the files in the archive. The following examples both
+extract members with long list output:
+
+@smallexample
+$ @kbd{tar --extract --file=archive.tar --verbose --verbose}
+$ @kbd{tar xvvf archive.tar}
+@end smallexample
+
+Verbose output appears on the standard output except when an archive is
+being written to the standard output, as with @samp{tar --create
+--file=- --verbose} (@samp{tar cfv -}, or even @samp{tar cv}---if the
+installer let standard output be the default archive). In that case
+@command{tar} writes verbose output to the standard error stream.
+
+If @option{--index-file=@var{file}} is specified, @command{tar} sends
+verbose output to @var{file} rather than to standard output or standard
+error.
+
+@cindex Obtaining total status information
+@opindex totals
+The @option{--totals} option---which is only meaningful when used with
+@option{--create} (@option{-c})---causes @command{tar} to print the total
+amount written to the archive, after it has been fully created.
+
+@cindex Progress information
+@opindex checkpoint
+The @option{--checkpoint} option prints an occasional message
+as @command{tar} reads or writes the archive. In fact, it prints
+a message each 10 records read or written. It is designed for
+those who don't need the more detailed (and voluminous) output of
+@option{--block-number} (@option{-R}), but do want visual confirmation that @command{tar}
+is actually making forward progress.
+
+@FIXME{There is some confusion here. It seems that -R once wrote a
+message at @samp{every} record read or written.}
+
+@opindex show-omitted-dirs
+@anchor{show-omitted-dirs}
+The @option{--show-omitted-dirs} option, when reading an archive---with
+@option{--list} or @option{--extract}, for example---causes a message
+to be printed for each directory in the archive which is skipped.
+This happens regardless of the reason for skipping: the directory might
+not have been named on the command line (implicitly or explicitly),
+it might be excluded by the use of the @option{--exclude=@var{pattern}} option, or
+some other reason.
+
+@opindex block-number
+@cindex Block number where error occurred
+@anchor{block-number}
+If @option{--block-number} (@option{-R}) is used, @command{tar} prints, along with
+every message it would normally produce, the block number within the
+archive where the message was triggered. Also, supplementary messages
+are triggered when reading blocks full of NULs, or when hitting end of
+file on the archive. As of now, if the archive if properly terminated
+with a NUL block, the reading of the file may stop before end of file
+is met, so the position of end of file will not usually show when
+@option{--block-number} (@option{-R}) is used. Note that @GNUTAR{}
+drains the archive before exiting when reading the
+archive from a pipe.
+
+@cindex Error message, block number of
+This option is especially useful when reading damaged archives, since
+it helps pinpoint the damaged sections. It can also be used with
+@option{--list} (@option{-t}) when listing a file-system backup tape, allowing you to
+choose among several backup tapes when retrieving a file later, in
+favor of the tape where the file appears earliest (closest to the
+front of the tape). @xref{backup}.
+
+@node interactive
+@section Asking for Confirmation During Operations
+@cindex Interactive operation
+
+Typically, @command{tar} carries out a command without stopping for
+further instructions. In some situations however, you may want to
+exclude some files and archive members from the operation (for instance
+if disk or storage space is tight). You can do this by excluding
+certain files automatically (@pxref{Choosing}), or by performing
+an operation interactively, using the @option{--interactive} (@option{-w}) option.
+@command{tar} also accepts @option{--confirmation} for this option.
+
+@opindex interactive
+When the @option{--interactive} (@option{-w}) option is specified, before
+reading, writing, or deleting files, @command{tar} first prints a message
+for each such file, telling what operation it intends to take, then asks
+for confirmation on the terminal. The actions which require
+confirmation include adding a file to the archive, extracting a file
+from the archive, deleting a file from the archive, and deleting a file
+from disk. To confirm the action, you must type a line of input
+beginning with @samp{y}. If your input line begins with anything other
+than @samp{y}, @command{tar} skips that file.
+
+If @command{tar} is reading the archive from the standard input,
+@command{tar} opens the file @file{/dev/tty} to support the interactive
+communications.
+
+Verbose output is normally sent to standard output, separate from
+other error messages. However, if the archive is produced directly
+on standard output, then verbose output is mixed with errors on
+@code{stderr}. Producing the archive on standard output may be used
+as a way to avoid using disk space, when the archive is soon to be
+consumed by another process reading it, say. Some people felt the need
+of producing an archive on stdout, still willing to segregate between
+verbose output and error output. A possible approach would be using a
+named pipe to receive the archive, and having the consumer process to
+read from that named pipe. This has the advantage of letting standard
+output free to receive verbose output, all separate from errors.
+
+@node operations
+@chapter @GNUTAR{} Operations
+
+@menu
+* Basic tar::
+* Advanced tar::
+* create options::
+* extract options::
+* backup::
+* Applications::
+* looking ahead::
+@end menu
+
+@node Basic tar
+@section Basic @GNUTAR{} Operations
+
+The basic @command{tar} operations, @option{--create} (@option{-c}),
+@option{--list} (@option{-t}) and @option{--extract} (@option{--get},
+@option{-x}), are currently presented and described in the tutorial
+chapter of this manual. This section provides some complementary notes
+for these operations.
+
+@table @option
+@opindex create, complementary notes
+@item --create
+@itemx -c
+
+Creating an empty archive would have some kind of elegance. One can
+initialize an empty archive and later use @option{--append}
+(@option{-r}) for adding all members. Some applications would not
+welcome making an exception in the way of adding the first archive
+member. On the other hand, many people reported that it is
+dangerously too easy for @command{tar} to destroy a magnetic tape with
+an empty archive@footnote{This is well described in @cite{Unix-haters
+Handbook}, by Simson Garfinkel, Daniel Weise & Steven Strassmann, IDG
+Books, ISBN 1-56884-203-1.}. The two most common errors are:
+
+@enumerate
+@item
+Mistakingly using @code{create} instead of @code{extract}, when the
+intent was to extract the full contents of an archive. This error
+is likely: keys @kbd{c} and @kbd{x} are right next to each other on
+the QWERTY keyboard. Instead of being unpacked, the archive then
+gets wholly destroyed. When users speak about @dfn{exploding} an
+archive, they usually mean something else :-).
+
+@item
+Forgetting the argument to @code{file}, when the intent was to create
+an archive with a single file in it. This error is likely because a
+tired user can easily add the @kbd{f} key to the cluster of option
+letters, by the mere force of habit, without realizing the full
+consequence of doing so. The usual consequence is that the single
+file, which was meant to be saved, is rather destroyed.
+@end enumerate
+
+So, recognizing the likelihood and the catastrophical nature of these
+errors, @GNUTAR{} now takes some distance from elegance, and
+cowardly refuses to create an archive when @option{--create} option is
+given, there are no arguments besides options, and
+@option{--files-from} (@option{-T}) option is @emph{not} used. To get
+around the cautiousness of @GNUTAR{} and nevertheless create an
+archive with nothing in it, one may still use, as the value for the
+@option{--files-from} option, a file with no names in it, as shown in
+the following commands:
+
+@smallexample
+@kbd{tar --create --file=empty-archive.tar --files-from=/dev/null}
+@kbd{tar cfT empty-archive.tar /dev/null}
+@end smallexample
+
+@opindex extract, complementary notes
+@item --extract
+@itemx --get
+@itemx -x
+
+A socket is stored, within a @GNUTAR{} archive, as a pipe.
+
+@item @option{--list} (@option{-t})
+
+@GNUTAR{} now shows dates as @samp{1996-08-30},
+while it used to show them as @samp{Aug 30 1996}. Preferably,
+people should get used to ISO 8601 dates. Local American dates should
+be made available again with full date localization support, once
+ready. In the meantime, programs not being localizable for dates
+should prefer international dates, that's really the way to go.
+
+Look up @url{http://www.ft.uni-erlangen.de/~mskuhn/iso-time.html} if you
+are curious, it contains a detailed explanation of the ISO 8601 standard.
+
+@end table
+
+@node Advanced tar
+@section Advanced @GNUTAR{} Operations
+
+Now that you have learned the basics of using @GNUTAR{}, you may want
+to learn about further ways in which @command{tar} can help you.
+
+This chapter presents five, more advanced operations which you probably
+won't use on a daily basis, but which serve more specialized functions.
+We also explain the different styles of options and why you might want
+to use one or another, or a combination of them in your @command{tar}
+commands. Additionally, this chapter includes options which allow you to
+define the output from @command{tar} more carefully, and provide help and
+error correction in special circumstances.
+
+@FIXME{check this after the chapter is actually revised to make sure
+it still introduces the info in the chapter correctly : ).}
+
+@menu
+* Operations::
+* append::
+* update::
+* concatenate::
+* delete::
+* compare::
+@end menu
+
+@node Operations
+@subsection The Five Advanced @command{tar} Operations
+@UNREVISED
+
+In the last chapter, you learned about the first three operations to
+@command{tar}. This chapter presents the remaining five operations to
+@command{tar}: @option{--append}, @option{--update}, @option{--concatenate},
+@option{--delete}, and @option{--compare}.
+
+You are not likely to use these operations as frequently as those
+covered in the last chapter; however, since they perform specialized
+functions, they are quite useful when you do need to use them. We
+will give examples using the same directory and files that you created
+in the last chapter. As you may recall, the directory is called
+@file{practice}, the files are @samp{jazz}, @samp{blues}, @samp{folk},
+@samp{rock}, and the two archive files you created are
+@samp{collection.tar} and @samp{music.tar}.
+
+We will also use the archive files @samp{afiles.tar} and
+@samp{bfiles.tar}. @samp{afiles.tar} contains the members @samp{apple},
+@samp{angst}, and @samp{aspic}. @samp{bfiles.tar} contains the members
+@samp{./birds}, @samp{baboon}, and @samp{./box}.
+
+Unless we state otherwise, all practicing you do and examples you follow
+in this chapter will take place in the @file{practice} directory that
+you created in the previous chapter; see @ref{prepare for examples}.
+(Below in this section, we will remind you of the state of the examples
+where the last chapter left them.)
+
+The five operations that we will cover in this chapter are:
+
+@table @option
+@item --append
+@itemx -r
+Add new entries to an archive that already exists.
+@item --update
+@itemx -r
+Add more recent copies of archive members to the end of an archive, if
+they exist.
+@item --concatenate
+@itemx --catenate
+@itemx -A
+Add one or more pre-existing archives to the end of another archive.
+@item --delete
+Delete items from an archive (does not work on tapes).
+@item --compare
+@itemx --diff
+@itemx -d
+Compare archive members to their counterparts in the file system.
+@end table
+
+@node append
+@subsection How to Add Files to Existing Archives: @option{--append}
+@UNREVISED
+
+@opindex append
+If you want to add files to an existing archive, you don't need to
+create a new archive; you can use @option{--append} (@option{-r}).
+The archive must already exist in order to use @option{--append}. (A
+related operation is the @option{--update} operation; you can use this
+to add newer versions of archive members to an existing archive. To learn how to
+do this with @option{--update}, @pxref{update}.)
+
+If you use @option{--append} to add a file that has the same name as an
+archive member to an archive containing that archive member, then the
+old member is not deleted. What does happen, however, is somewhat
+complex. @command{tar} @emph{allows} you to have infinite number of files
+with the same name. Some operations treat these same-named members no
+differently than any other set of archive members: for example, if you
+view an archive with @option{--list} (@option{-t}), you will see all
+of those members listed, with their data modification times, owners, etc.
+
+Other operations don't deal with these members as perfectly as you might
+prefer; if you were to use @option{--extract} to extract the archive,
+only the most recently added copy of a member with the same name as four
+other members would end up in the working directory. This is because
+@option{--extract} extracts an archive in the order the members appeared
+in the archive; the most recently archived members will be extracted
+last. Additionally, an extracted member will @emph{replace} a file of
+the same name which existed in the directory already, and @command{tar}
+will not prompt you about this@footnote{Unless you give it
+@option{--keep-old-files} option, or the disk copy is newer than the
+the one in the archive and you invoke @command{tar} with
+@option{--keep-newer-files} option}. Thus, only the most recently archived
+member will end up being extracted, as it will replace the one
+extracted before it, and so on.
+
+There exists a special option that allows you to get around this
+behavior and extract (or list) only a particular copy of the file.
+This is @option{--occurrence} option. If you run @command{tar} with
+this option, it will extract only the first copy of the file. You
+may also give this option an argument specifying the number of
+copy to be extracted. Thus, for example if the archive
+@file{archive.tar} contained three copies of file @file{myfile}, then
+the command
+
+@smallexample
+tar --extract --file archive.tar --occurrence=2 myfile
+@end smallexample
+
+@noindent
+would extract only the second copy. @xref{Option
+Summary,---occurrence}, for the description of @option{--occurrence}
+option.
+
+@FIXME{ hag -- you might want to incorporate some of the above into the
+MMwtSN node; not sure. i didn't know how to make it simpler...
+
+There are a few ways to get around this. (maybe xref Multiple Members
+with the Same Name.}
+
+@cindex Members, replacing with other members
+@cindex Replacing members with other members
+If you want to replace an archive member, use @option{--delete} to
+delete the member you want to remove from the archive, , and then use
+@option{--append} to add the member you want to be in the archive. Note
+that you can not change the order of the archive; the most recently
+added member will still appear last. In this sense, you cannot truly
+``replace'' one member with another. (Replacing one member with another
+will not work on certain types of media, such as tapes; see @ref{delete}
+and @ref{Media}, for more information.)
+
+@menu
+* appending files:: Appending Files to an Archive
+* multiple::
+@end menu
+
+@node appending files
+@subsubsection Appending Files to an Archive
+@UNREVISED
+@cindex Adding files to an Archive
+@cindex Appending files to an Archive
+@cindex Archives, Appending files to
+
+The simplest way to add a file to an already existing archive is the
+@option{--append} (@option{-r}) operation, which writes specified files into the
+archive whether or not they are already among the archived files.
+When you use @option{--append}, you @emph{must} specify file name
+arguments, as there is no default. If you specify a file that already
+exists in the archive, another copy of the file will be added to the
+end of the archive. As with other operations, the member names of the
+newly added files will be exactly the same as their names given on the
+command line. The @option{--verbose} (@option{-v}) option will print
+out the names of the files as they are written into the archive.
+
+@option{--append} cannot be performed on some tape drives, unfortunately,
+due to deficiencies in the formats those tape drives use. The archive
+must be a valid @command{tar} archive, or else the results of using this
+operation will be unpredictable. @xref{Media}.
+
+To demonstrate using @option{--append} to add a file to an archive,
+create a file called @file{rock} in the @file{practice} directory.
+Make sure you are in the @file{practice} directory. Then, run the
+following @command{tar} command to add @file{rock} to
+@file{collection.tar}:
+
+@smallexample
+$ @kbd{tar --append --file=collection.tar rock}
+@end smallexample
+
+@noindent
+If you now use the @option{--list} (@option{-t}) operation, you will see that
+@file{rock} has been added to the archive:
+
+@smallexample
+$ @kbd{tar --list --file=collection.tar}
+-rw-r--r-- me user 28 1996-10-18 16:31 jazz
+-rw-r--r-- me user 21 1996-09-23 16:44 blues
+-rw-r--r-- me user 20 1996-09-23 16:44 folk
+-rw-r--r-- me user 20 1996-09-23 16:44 rock
+@end smallexample
+
+@FIXME{in theory, dan will (soon) try to turn this node into what it's
+title claims it will become...}
+
+@node multiple
+@subsubsection Multiple Files with the Same Name
+
+You can use @option{--append} (@option{-r}) to add copies of files which have been
+updated since the archive was created. (However, we do not recommend
+doing this since there is another @command{tar} option called
+@option{--update}; @pxref{update} for more information. We describe this
+use of @option{--append} here for the sake of completeness.) @FIXME{is
+this really a good idea, to give this whole description for something
+which i believe is basically a Stupid way of doing something? certain
+aspects of it show ways in which tar is more broken than i'd personally
+like to admit to, specifically the last sentence. On the other hand, i
+don't think it's a good idea to be saying that we explicitly don't
+recommend using something, but i can't see any better way to deal with
+the situation.}When you extract the archive, the older version will be
+effectively lost. This works because files are extracted from an
+archive in the order in which they were archived. Thus, when the
+archive is extracted, a file archived later in time will replace a
+file of the same name which was archived earlier, even though the older
+version of the file will remain in the archive unless you delete all
+versions of the file.
+
+Supposing you change the file @file{blues} and then append the changed
+version to @file{collection.tar}. As you saw above, the original
+@file{blues} is in the archive @file{collection.tar}. If you change the
+file and append the new version of the file to the archive, there will
+be two copies in the archive. When you extract the archive, the older
+version of the file will be extracted first, and then replaced by the
+newer version when it is extracted.
+
+You can append the new, changed copy of the file @file{blues} to the
+archive in this way:
+
+@smallexample
+$ @kbd{tar --append --verbose --file=collection.tar blues}
+blues
+@end smallexample
+
+@noindent
+Because you specified the @option{--verbose} option, @command{tar} has
+printed the name of the file being appended as it was acted on. Now
+list the contents of the archive:
+
+@smallexample
+$ @kbd{tar --list --verbose --file=collection.tar}
+-rw-r--r-- me user 28 1996-10-18 16:31 jazz
+-rw-r--r-- me user 21 1996-09-23 16:44 blues
+-rw-r--r-- me user 20 1996-09-23 16:44 folk
+-rw-r--r-- me user 20 1996-09-23 16:44 rock
+-rw-r--r-- me user 58 1996-10-24 18:30 blues
+@end smallexample
+
+@noindent
+The newest version of @file{blues} is now at the end of the archive
+(note the different creation dates and file sizes). If you extract
+the archive, the older version of the file @file{blues} will be
+replaced by the newer version. You can confirm this by extracting
+the archive and running @samp{ls} on the directory.
+
+If you wish to extract the first occurrence of the file @file{blues}
+from the archive, use @option{--occurrence} option, as shown in
+the following example:
+
+@smallexample
+$ @kbd{tar --extract -vv --occurrence --file=collection.tar blues}
+-rw-r--r-- me user 21 1996-09-23 16:44 blues
+@end smallexample
+
+@xref{Writing}, for more information on @option{--extract} and
+@xref{Option Summary, --occurrence}, for the description of
+@option{--occurrence} option.
+
+@node update
+@subsection Updating an Archive
+@UNREVISED
+@cindex Updating an archive
+
+@opindex update
+In the previous section, you learned how to use @option{--append} to
+add a file to an existing archive. A related operation is
+@option{--update} (@option{-u}). The @option{--update} operation
+updates a @command{tar} archive by comparing the date of the specified
+archive members against the date of the file with the same name. If
+the file has been modified more recently than the archive member, then
+the newer version of the file is added to the archive (as with
+@option{--append}).
+
+Unfortunately, you cannot use @option{--update} with magnetic tape drives.
+The operation will fail.
+
+@FIXME{other examples of media on which --update will fail? need to ask
+charles and/or mib/thomas/dave shevett..}
+
+Both @option{--update} and @option{--append} work by adding to the end
+of the archive. When you extract a file from the archive, only the
+version stored last will wind up in the file system, unless you use
+the @option{--backup} option. @FIXME-ref{Multiple Members with the
+Same Name}
+
+@menu
+* how to update::
+@end menu
+
+@node how to update
+@subsubsection How to Update an Archive Using @option{--update}
+
+You must use file name arguments with the @option{--update} (@option{-u}) operation.
+If you don't specify any files, @command{tar} won't act on any files and
+won't tell you that it didn't do anything (which may end up confusing
+you).
+
+@FIXME{note: the above parenthetical added because in fact, this
+behavior just confused the author. :-) }
+
+To see the @option{--update} option at work, create a new file,
+@file{classical}, in your practice directory, and some extra text to the
+file @file{blues}, using any text editor. Then invoke @command{tar} with
+the @samp{update} operation and the @option{--verbose} (@option{-v}) option specified,
+using the names of all the files in the practice directory as file name
+arguments:
+
+@smallexample
+$ @kbd{tar --update -v -f collection.tar blues folk rock classical}
+blues
+classical
+$
+@end smallexample
+
+@noindent
+Because we have specified verbose mode, @command{tar} prints out the names
+of the files it is working on, which in this case are the names of the
+files that needed to be updated. If you run @samp{tar --list} and look
+at the archive, you will see @file{blues} and @file{classical} at its
+end. There will be a total of two versions of the member @samp{blues};
+the one at the end will be newer and larger, since you added text before
+updating it.
+
+(The reason @command{tar} does not overwrite the older file when updating
+it is because writing to the middle of a section of tape is a difficult
+process. Tapes are not designed to go backward. @xref{Media}, for more
+information about tapes.
+
+@option{--update} (@option{-u}) is not suitable for performing backups for two
+reasons: it does not change directory content entries, and it
+lengthens the archive every time it is used. The @GNUTAR{}
+options intended specifically for backups are more
+efficient. If you need to run backups, please consult @ref{Backups}.
+
+@node concatenate
+@subsection Combining Archives with @option{--concatenate}
+
+@cindex Adding archives to an archive
+@cindex Concatenating Archives
+@opindex concatenate
+@opindex catenate
+@c @cindex @option{-A} described
+Sometimes it may be convenient to add a second archive onto the end of
+an archive rather than adding individual files to the archive. To add
+one or more archives to the end of another archive, you should use the
+@option{--concatenate} (@option{--catenate}, @option{-A}) operation.
+
+To use @option{--concatenate}, give the first archive with
+@option{--file} option and name the rest of archives to be
+concatenated on the command line. The members, and their member
+names, will be copied verbatim from those archives to the first one.
+@FIXME-ref{This can cause multiple members to have the same name, for
+information on how this affects reading the archive, Multiple
+Members with the Same Name.}
+The new, concatenated archive will be called by the same name as the
+one given with the @option{--file} option. As usual, if you omit
+@option{--file}, @command{tar} will use the value of the environment
+variable @env{TAPE}, or, if this has not been set, the default archive name.
+
+@FIXME{There is no way to specify a new name...}
+
+To demonstrate how @option{--concatenate} works, create two small archives
+called @file{bluesrock.tar} and @file{folkjazz.tar}, using the relevant
+files from @file{practice}:
+
+@smallexample
+$ @kbd{tar -cvf bluesrock.tar blues rock}
+blues
+classical
+$ @kbd{tar -cvf folkjazz.tar folk jazz}
+folk
+jazz
+@end smallexample
+
+@noindent
+If you like, You can run @samp{tar --list} to make sure the archives
+contain what they are supposed to:
+
+@smallexample
+$ @kbd{tar -tvf bluesrock.tar}
+-rw-r--r-- melissa user 105 1997-01-21 19:42 blues
+-rw-r--r-- melissa user 33 1997-01-20 15:34 rock
+$ @kbd{tar -tvf folkjazz.tar}
+-rw-r--r-- melissa user 20 1996-09-23 16:44 folk
+-rw-r--r-- melissa user 65 1997-01-30 14:15 jazz
+@end smallexample
+
+We can concatenate these two archives with @command{tar}:
+
+@smallexample
+$ @kbd{cd ..}
+$ @kbd{tar --concatenate --file=bluesrock.tar jazzfolk.tar}
+@end smallexample
+
+If you now list the contents of the @file{bluesclass.tar}, you will see
+that now it also contains the archive members of @file{jazzfolk.tar}:
+
+@smallexample
+$ @kbd{tar --list --file=bluesrock.tar}
+blues
+rock
+jazz
+folk
+@end smallexample
+
+When you use @option{--concatenate}, the source and target archives must
+already exist and must have been created using compatible format
+parameters. Notice, that @command{tar} does not check whether the
+archives it concatenates have compatible formats, it does not
+even check if the files are really tar archives.
+
+Like @option{--append} (@option{-r}), this operation cannot be performed on some
+tape drives, due to deficiencies in the formats those tape drives use.
+
+@cindex @code{concatenate} vs @command{cat}
+@cindex @command{cat} vs @code{concatenate}
+It may seem more intuitive to you to want or try to use @command{cat} to
+concatenate two archives instead of using the @option{--concatenate}
+operation; after all, @command{cat} is the utility for combining files.
+
+However, @command{tar} archives incorporate an end-of-file marker which
+must be removed if the concatenated archives are to be read properly as
+one archive. @option{--concatenate} removes the end-of-archive marker
+from the target archive before each new archive is appended. If you use
+@command{cat} to combine the archives, the result will not be a valid
+@command{tar} format archive. If you need to retrieve files from an
+archive that was added to using the @command{cat} utility, use the
+@option{--ignore-zeros} (@option{-i}) option. @xref{Ignore Zeros}, for further
+information on dealing with archives improperly combined using the
+@command{cat} shell utility.
+
+@node delete
+@subsection Removing Archive Members Using @option{--delete}
+@UNREVISED
+@cindex Deleting files from an archive
+@cindex Removing files from an archive
+
+@opindex delete
+You can remove members from an archive by using the @option{--delete}
+option. Specify the name of the archive with @option{--file}
+(@option{-f}) and then specify the names of the members to be deleted;
+if you list no member names, nothing will be deleted. The
+@option{--verbose} option will cause @command{tar} to print the names
+of the members as they are deleted. As with @option{--extract}, you
+must give the exact member names when using @samp{tar --delete}.
+@option{--delete} will remove all versions of the named file from the
+archive. The @option{--delete} operation can run very slowly.
+
+Unlike other operations, @option{--delete} has no short form.
+
+@cindex Tapes, using @option{--delete} and
+@cindex Deleting from tape archives
+This operation will rewrite the archive. You can only use
+@option{--delete} on an archive if the archive device allows you to
+write to any point on the media, such as a disk; because of this, it
+does not work on magnetic tapes. Do not try to delete an archive member
+from a magnetic tape; the action will not succeed, and you will be
+likely to scramble the archive and damage your tape. There is no safe
+way (except by completely re-writing the archive) to delete files from
+most kinds of magnetic tape. @xref{Media}.
+
+To delete all versions of the file @file{blues} from the archive
+@file{collection.tar} in the @file{practice} directory, make sure you
+are in that directory, and then,
+
+@smallexample
+$ @kbd{tar --list --file=collection.tar}
+blues
+folk
+jazz
+rock
+practice/blues
+practice/folk
+practice/jazz
+practice/rock
+practice/blues
+$ @kbd{tar --delete --file=collection.tar blues}
+$ @kbd{tar --list --file=collection.tar}
+folk
+jazz
+rock
+$
+@end smallexample
+
+@FIXME{I changed the order of these nodes around and haven't had a chance
+to fix the above example's results, yet. I have to play with this and
+follow it and see what it actually does!}
+
+The @option{--delete} option has been reported to work properly when
+@command{tar} acts as a filter from @code{stdin} to @code{stdout}.
+
+@node compare
+@subsection Comparing Archive Members with the File System
+@cindex Verifying the currency of an archive
+@UNREVISED
+
+@opindex compare
+The @option{--compare} (@option{-d}), or @option{--diff} operation compares
+specified archive members against files with the same names, and then
+reports differences in file size, mode, owner, modification date and
+contents. You should @emph{only} specify archive member names, not file
+names. If you do not name any members, then @command{tar} will compare the
+entire archive. If a file is represented in the archive but does not
+exist in the file system, @command{tar} reports a difference.
+
+You have to specify the record size of the archive when modifying an
+archive with a non-default record size.
+
+@command{tar} ignores files in the file system that do not have
+corresponding members in the archive.
+
+The following example compares the archive members @file{rock},
+@file{blues} and @file{funk} in the archive @file{bluesrock.tar} with
+files of the same name in the file system. (Note that there is no file,
+@file{funk}; @command{tar} will report an error message.)
+
+@smallexample
+$ @kbd{tar --compare --file=bluesrock.tar rock blues funk}
+rock
+blues
+tar: funk not found in archive
+@end smallexample
+
+The spirit behind the @option{--compare} (@option{--diff}, @option{-d}) option is to check whether the
+archive represents the current state of files on disk, more than validating
+the integrity of the archive media. For this later goal, @xref{verify}.
+
+@node create options
+@section Options Used by @option{--create}
+
+@opindex create, additional options
+The previous chapter described the basics of how to use
+@option{--create} (@option{-c}) to create an archive from a set of files.
+@xref{create}. This section described advanced options to be used with
+@option{--create}.
+
+@menu
+* Ignore Failed Read::
+@end menu
+
+@node Ignore Failed Read
+@subsection Ignore Fail Read
+
+@table @option
+@item --ignore-failed-read
+Do not exit with nonzero on unreadable files or directories.
+@end table
+
+@node extract options
+@section Options Used by @option{--extract}
+@UNREVISED
+
+@FIXME{i need to get dan to go over these options with me and see if
+there's a better way of organizing them.}
+
+@opindex extract, additional options
+The previous chapter showed how to use @option{--extract} to extract
+an archive into the file system. Various options cause @command{tar} to
+extract more information than just file contents, such as the owner,
+the permissions, the modification date, and so forth. This section
+presents options to be used with @option{--extract} when certain special
+considerations arise. You may review the information presented in
+@ref{extract} for more basic information about the
+@option{--extract} operation.
+
+@menu
+* Reading:: Options to Help Read Archives
+* Writing:: Changing How @command{tar} Writes Files
+* Scarce:: Coping with Scarce Resources
+@end menu
+
+@node Reading
+@subsection Options to Help Read Archives
+@cindex Options when reading archives
+@UNREVISED
+
+@cindex Reading incomplete records
+@cindex Records, incomplete
+@opindex read-full-records
+Normally, @command{tar} will request data in full record increments from
+an archive storage device. If the device cannot return a full record,
+@command{tar} will report an error. However, some devices do not always
+return full records, or do not require the last record of an archive to
+be padded out to the next record boundary. To keep reading until you
+obtain a full record, or to accept an incomplete record if it contains
+an end-of-archive marker, specify the @option{--read-full-records} (@option{-B}) option
+in conjunction with the @option{--extract} or @option{--list} operations.
+@xref{Blocking}.
+
+The @option{--read-full-records} (@option{-B}) option is turned on by default when
+@command{tar} reads an archive from standard input, or from a remote
+machine. This is because on BSD Unix systems, attempting to read a
+pipe returns however much happens to be in the pipe, even if it is
+less than was requested. If this option were not enabled, @command{tar}
+would fail as soon as it read an incomplete record from the pipe.
+
+If you're not sure of the blocking factor of an archive, you can
+read the archive by specifying @option{--read-full-records} (@option{-B}) and
+@option{--blocking-factor=@var{512-size}} (@option{-b
+@var{512-size}}), using a blocking factor larger than what the archive
+uses. This lets you avoid having to determine the blocking factor
+of an archive. @xref{Blocking Factor}.
+
+@menu
+* read full records::
+* Ignore Zeros::
+@end menu
+
+@node read full records
+@unnumberedsubsubsec Reading Full Records
+
+@FIXME{need sentence or so of intro here}
+
+@table @option
+@opindex read-full-records
+@item --read-full-records
+@item -B
+Use in conjunction with @option{--extract} (@option{--get},
+@option{-x}) to read an archive which contains incomplete records, or
+one which has a blocking factor less than the one specified.
+@end table
+
+@node Ignore Zeros
+@unnumberedsubsubsec Ignoring Blocks of Zeros
+
+@cindex End-of-archive blocks, ignoring
+@cindex Ignoring end-of-archive blocks
+@opindex ignore-zeros
+Normally, @command{tar} stops reading when it encounters a block of zeros
+between file entries (which usually indicates the end of the archive).
+@option{--ignore-zeros} (@option{-i}) allows @command{tar} to
+completely read an archive which contains a block of zeros before the
+end (i.e., a damaged archive, or one that was created by concatenating
+several archives together).
+
+The @option{--ignore-zeros} (@option{-i}) option is turned off by default because many
+versions of @command{tar} write garbage after the end-of-archive entry,
+since that part of the media is never supposed to be read. @GNUTAR{}
+does not write after the end of an archive, but seeks to
+maintain compatiblity among archiving utilities.
+
+@table @option
+@item --ignore-zeros
+@itemx -i
+To ignore blocks of zeros (i.e., end-of-archive entries) which may be
+encountered while reading an archive. Use in conjunction with
+@option{--extract} or @option{--list}.
+@end table
+
+@node Writing
+@subsection Changing How @command{tar} Writes Files
+@UNREVISED
+
+@FIXME{Introductory paragraph}
+
+@menu
+* Dealing with Old Files::
+* Overwrite Old Files::
+* Keep Old Files::
+* Keep Newer Files::
+* Unlink First::
+* Recursive Unlink::
+* Data Modification Times::
+* Setting Access Permissions::
+* Directory Modification Times and Permissions::
+* Writing to Standard Output::
+* Writing to an External Program::
+* remove files::
+@end menu
+
+@node Dealing with Old Files
+@unnumberedsubsubsec Options Controlling the Overwriting of Existing Files
+
+@opindex overwrite-dir, introduced
+When extracting files, if @command{tar} discovers that the extracted
+file already exists, it normally replaces the file by removing it before
+extracting it, to prevent confusion in the presence of hard or symbolic
+links. (If the existing file is a symbolic link, it is removed, not
+followed.) However, if a directory cannot be removed because it is
+nonempty, @command{tar} normally overwrites its metadata (ownership,
+permission, etc.). The @option{--overwrite-dir} option enables this
+default behavior. To be more cautious and preserve the metadata of
+such a directory, use the @option{--no-overwrite-dir} option.
+
+@cindex Overwriting old files, prevention
+@opindex keep-old-files, introduced
+To be even more cautious and prevent existing files from being replaced, use
+the @option{--keep-old-files} (@option{-k}) option. It causes @command{tar} to refuse
+to replace or update a file that already exists, i.e., a file with the
+same name as an archive member prevents extraction of that archive
+member. Instead, it reports an error.
+
+@opindex overwrite, introduced
+To be more aggressive about altering existing files, use the
+@option{--overwrite} option. It causes @command{tar} to overwrite
+existing files and to follow existing symbolic links when extracting.
+
+@cindex Protecting old files
+Some people argue that @GNUTAR{} should not hesitate
+to overwrite files with other files when extracting. When extracting
+a @command{tar} archive, they expect to see a faithful copy of the
+state of the file system when the archive was created. It is debatable
+that this would always be a proper behavior. For example, suppose one
+has an archive in which @file{usr/local} is a link to
+@file{usr/local2}. Since then, maybe the site removed the link and
+renamed the whole hierarchy from @file{/usr/local2} to
+@file{/usr/local}. Such things happen all the time. I guess it would
+not be welcome at all that @GNUTAR{} removes the
+whole hierarchy just to make room for the link to be reinstated
+(unless it @emph{also} simultaneously restores the full
+@file{/usr/local2}, of course!) @GNUTAR{} is indeed
+able to remove a whole hierarchy to reestablish a symbolic link, for
+example, but @emph{only if} @option{--recursive-unlink} is specified
+to allow this behavior. In any case, single files are silently
+removed.
+
+@opindex unlink-first, introduced
+Finally, the @option{--unlink-first} (@option{-U}) option can improve performance in
+some cases by causing @command{tar} to remove files unconditionally
+before extracting them.
+
+@node Overwrite Old Files
+@unnumberedsubsubsec Overwrite Old Files
+
+@table @option
+@opindex overwrite
+@item --overwrite
+Overwrite existing files and directory metadata when extracting files
+from an archive.
+
+This causes @command{tar} to write extracted files into the file system without
+regard to the files already on the system; i.e., files with the same
+names as archive members are overwritten when the archive is extracted.
+It also causes @command{tar} to extract the ownership, permissions,
+and time stamps onto any preexisting files or directories.
+If the name of a corresponding file name is a symbolic link, the file
+pointed to by the symbolic link will be overwritten instead of the
+symbolic link itself (if this is possible). Moreover, special devices,
+empty directories and even symbolic links are automatically removed if
+they are in the way of extraction.
+
+Be careful when using the @option{--overwrite} option, particularly when
+combined with the @option{--absolute-names} (@option{-P}) option, as this combination
+can change the contents, ownership or permissions of any file on your
+system. Also, many systems do not take kindly to overwriting files that
+are currently being executed.
+
+@opindex overwrite-dir
+@item --overwrite-dir
+Overwrite the metadata of directories when extracting files from an
+archive, but remove other files before extracting.
+@end table
+
+@node Keep Old Files
+@unnumberedsubsubsec Keep Old Files
+
+@table @option
+@opindex keep-old-files
+@item --keep-old-files
+@itemx -k
+Do not replace existing files from archive. The
+@option{--keep-old-files} (@option{-k}) option prevents @command{tar}
+from replacing existing files with files with the same name from the
+archive. The @option{--keep-old-files} option is meaningless with
+@option{--list} (@option{-t}). Prevents @command{tar} from replacing
+files in the file system during extraction.
+@end table
+
+@node Keep Newer Files
+@unnumberedsubsubsec Keep Newer Files
+
+@table @option
+@opindex keep-newer-files
+@item --keep-newer-files
+Do not replace existing files that are newer than their archive
+copies. This option is meaningless with @option{--list} (@option{-t}).
+@end table
+
+@node Unlink First
+@unnumberedsubsubsec Unlink First
+
+@table @option
+@opindex unlink-first
+@item --unlink-first
+@itemx -U
+Remove files before extracting over them.
+This can make @command{tar} run a bit faster if you know in advance
+that the extracted files all need to be removed. Normally this option
+slows @command{tar} down slightly, so it is disabled by default.
+@end table
+
+@node Recursive Unlink
+@unnumberedsubsubsec Recursive Unlink
+
+@table @option
+@opindex recursive-unlink
+@item --recursive-unlink
+When this option is specified, try removing files and directory hierarchies
+before extracting over them. @emph{This is a dangerous option!}
+@end table
+
+If you specify the @option{--recursive-unlink} option,
+@command{tar} removes @emph{anything} that keeps you from extracting a file
+as far as current permissions will allow it. This could include removal
+of the contents of a full directory hierarchy.
+
+@node Data Modification Times
+@unnumberedsubsubsec Setting Data Modification Times
+
+@cindex Data modification times of extracted files
+@cindex Modification times of extracted files
+Normally, @command{tar} sets the data modification times of extracted
+files to the corresponding times recorded for the files in the archive, but
+limits the permissions of extracted files by the current @code{umask}
+setting.
+
+To set the data modification times of extracted files to the time when
+the files were extracted, use the @option{--touch} (@option{-m}) option in
+conjunction with @option{--extract} (@option{--get}, @option{-x}).
+
+@table @option
+@opindex touch
+@item --touch
+@itemx -m
+Sets the data modification time of extracted archive members to the time
+they were extracted, not the time recorded for them in the archive.
+Use in conjunction with @option{--extract} (@option{--get}, @option{-x}).
+@end table
+
+@node Setting Access Permissions
+@unnumberedsubsubsec Setting Access Permissions
+
+@cindex Permissions of extracted files
+@cindex Modes of extracted files
+To set the modes (access permissions) of extracted files to those
+recorded for those files in the archive, use @option{--same-permissions}
+in conjunction with the @option{--extract} (@option{--get},
+@option{-x}) operation. @FIXME{Should be aliased to ignore-umask.}
+
+@table @option
+@opindex preserve-permission
+@opindex same-permission
+@item --preserve-permission
+@itemx --same-permission
+@c @itemx --ignore-umask
+@itemx -p
+Set modes of extracted archive members to those recorded in the
+archive, instead of current umask settings. Use in conjunction with
+@option{--extract} (@option{--get}, @option{-x}).
+@end table
+
+@node Directory Modification Times and Permissions
+@unnumberedsubsubsec Directory Modification Times and Permissions
+
+After sucessfully extracting a file member, @GNUTAR{} normally
+restores its permissions and modification times, as described in the
+previous sections. This cannot be done for directories, because
+after extracting a directory @command{tar} will almost certainly
+extract files into that directory and this will cause the directory
+modification time to be updated. Moreover, restoring that directory
+permissions may not permit file creation within it. Thus, restoring
+directory permissions and modification times must be delayed at least
+until all files have been extracted into that directory. @GNUTAR{}
+restores directories using the following approach.
+
+The extracted directories are created with the mode specified in the
+archive, as modified by the umask of the user, which gives sufficient
+permissions to allow file creation. The meta-information about the
+directory is recorded in the temporary list of directories. When
+preparing to extract next archive member, @GNUTAR{} checks if the
+directory prefix of this file contains the remembered directory. If
+it does not, the program assumes that all files have been extracted
+into that directory, restores its modification time and permissions
+and removes its entry from the internal list. This approach allows
+to correctly restore directory meta-information in the majority of
+cases, while keeping memory requirements sufficiently small. It is
+based on the fact, that most @command{tar} archives use the predefined
+order of members: first the directory, then all the files and
+subdirectories in that directory.
+
+However, this is not always true. The most important exception are
+incremental archives (@pxref{Incremental Dumps}). The member order in
+an incremental archive is reversed: first all directory members are
+stored, followed by other (non-directory) members. So, when extracting
+from incremental archives, @GNUTAR{} alters the above procedure. It
+remebers all restored directories, and restores their meta-data
+only after the entire archive has been processed. Notice, that you do
+not need to specity any special options for that, as @GNUTAR{}
+automatically detects archives in incremental format.
+
+There may be cases, when such processing is required for normal archives
+too. Consider the following example:
+
+@smallexample
+@group
+$ @kbd{tar --no-recursion -cvf archive \
+ foo foo/file1 bar bar/file foo/file2}
+foo/
+foo/file1
+bar/
+bar/file
+foo/file2
+@end group
+@end smallexample
+
+During the normal operation, after encountering @file{bar}
+@GNUTAR{} will assume that all files from the directory @file{foo}
+were already extracted and will therefore restore its timestamp and
+permission bits. However, after extracting @file{foo/file2} the
+directory timestamp will be offset again.
+
+To correctly restore directory meta-information in such cases, use
+@option{delay-directory-restore} command line option:
+
+@table @option
+@opindex delay-directory-restore
+@item --delay-directory-restore
+Delays restoring of the modification times and permissions of extracted
+directories until the end of extraction. This way, correct
+meta-information is restored even if the archive has unusual member
+ordering.
+
+@opindex no-delay-directory-restore
+@item --no-delay-directory-restore
+Cancel the effect of the previous @option{--delay-directory-restore}.
+Use this option if you have used @option{--delay-directory-restore} in
+@env{TAR_OPTIONS} variable (@pxref{TAR_OPTIONS}) and wish to
+temporarily disable it.
+@end table
+
+@node Writing to Standard Output
+@unnumberedsubsubsec Writing to Standard Output
+
+@cindex Writing extracted files to standard output
+@cindex Standard output, writing extracted files to
+To write the extracted files to the standard output, instead of
+creating the files on the file system, use @option{--to-stdout} (@option{-O}) in
+conjunction with @option{--extract} (@option{--get}, @option{-x}). This option is useful if you are
+extracting files to send them through a pipe, and do not need to
+preserve them in the file system. If you extract multiple members,
+they appear on standard output concatenated, in the order they are
+found in the archive.
+
+@table @option
+@opindex to-stdout
+@item --to-stdout
+@itemx -O
+Writes files to the standard output. Use only in conjunction with
+@option{--extract} (@option{--get}, @option{-x}). When this option is
+used, instead of creating the files specified, @command{tar} writes
+the contents of the files extracted to its standard output. This may
+be useful if you are only extracting the files in order to send them
+through a pipe. This option is meaningless with @option{--list}
+(@option{-t}).
+@end table
+
+This can be useful, for example, if you have a tar archive containing
+a big file and don't want to store the file on disk before processing
+it. You can use a command like this:
+
+@smallexample
+tar -xOzf foo.tgz bigfile | process
+@end smallexample
+
+or even like this if you want to process the concatenation of the files:
+
+@smallexample
+tar -xOzf foo.tgz bigfile1 bigfile2 | process
+@end smallexample
+
+Hovewer, @option{--to-command} may be more convenient for use with
+multiple files. See the next section.
+
+@node Writing to an External Program
+@unnumberedsubsubsec Writing to an External Program
+
+You can instruct @command{tar} to send the contents of each extracted
+file to the standard input of an external program:
+
+@table @option
+@opindex to-program
+@item --to-program=@var{command}
+Extract files and pipe their contents to the standard input of
+@var{command}. When this option is used, instead of creating the
+files specified, @command{tar} invokes @var{command} and pipes the
+contents of the files to its standard output. @var{Command} may
+contain command line arguments. The program is executed via
+@code{sh -c}. Notice, that @var{command} is executed once for each regular file
+extracted. Non-regular files (directories, etc.) are ignored when this
+option is used.
+@end table
+
+The command can obtain the information about the file it processes
+from the following environment variables:
+
+@table @var
+@vrindex TAR_FILETYPE, to-command environment
+@item TAR_FILETYPE
+Type of the file. It is a single letter with the following meaning:
+
+@multitable @columnfractions 0.10 0.90
+@item f @tab Regular file
+@item d @tab Directory
+@item l @tab Symbolic link
+@item h @tab Hard link
+@item b @tab Block device
+@item c @tab Character device
+@end multitable
+
+Currently only regular files are supported.
+
+@vrindex TAR_MODE, to-command environment
+@item TAR_MODE
+File mode, an octal number.
+
+@vrindex TAR_FILENAME, to-command environment
+@item TAR_FILENAME
+The name of the file.
+
+@vrindex TAR_REALNAME, to-command environment
+@item TAR_REALNAME
+Name of the file as stored in the archive.
+
+@vrindex TAR_UNAME, to-command environment
+@item TAR_UNAME
+Name of the file owner.
+
+@vrindex TAR_GNAME, to-command environment
+@item TAR_GNAME
+Name of the file owner group.
+
+@vrindex TAR_ATIME, to-command environment
+@item TAR_ATIME
+Time of last access. It is a decimal number, representing seconds
+since the epoch. If the archive provides times with nanosecond
+precision, the nanoseconds are appended to the timestamp after a
+decimal point.
+
+@vrindex TAR_MTIME, to-command environment
+@item TAR_MTIME
+Time of last modification.
+
+@vrindex TAR_CTIME, to-command environment
+@item TAR_CTIME
+Time of last status change.
+
+@vrindex TAR_SIZE, to-command environment
+@item TAR_SIZE
+Size of the file.
+
+@vrindex TAR_UID, to-command environment
+@item TAR_UID
+UID of the file owner.
+
+@vrindex TAR_GID, to-command environment
+@item TAR_GID
+GID of the file owner.
+@end table
+
+In addition to these variables, @env{TAR_VERSION} contains the
+@GNUTAR{} version number.
+
+If @var{command} exits with a non-0 status, @command{tar} will print
+an error message similar to the following:
+
+@smallexample
+tar: 2345: Child returned status 1
+@end smallexample
+
+Here, @samp{2345} is the PID of the finished process.
+
+If this behavior is not wanted, use @option{--ignore-command-error}:
+
+@table @option
+@opindex ignore-command-error
+@item --ignore-command-error
+Ignore exit codes of subprocesses. Notice that if the program
+exits on signal or otherwise terminates abnormally, the error message
+will be printed even if this option is used.
+
+@opindex no-ignore-command-error
+@item --no-ignore-command-error
+Cancel the effect of any previous @option{--ignore-command-error}
+option. This option is useful if you have set
+@option{--ignore-command-error} in @env{TAR_OPTIONS}
+(@pxref{TAR_OPTIONS}) and wish to temporarily cancel it.
+@end table
+
+@node remove files
+@unnumberedsubsubsec Removing Files
+
+@FIXME{the various macros in the front of the manual think that this
+option goes in this section. i have no idea; i only know it's nowhere
+else in the book...}
+
+@table @option
+@opindex remove-files
+@item --remove-files
+Remove files after adding them to the archive.
+@end table
+
+@node Scarce
+@subsection Coping with Scarce Resources
+@UNREVISED
+
+@cindex Small memory
+@cindex Running out of space
+
+@menu
+* Starting File::
+* Same Order::
+@end menu
+
+@node Starting File
+@unnumberedsubsubsec Starting File
+
+@table @option
+@opindex starting-file
+@item --starting-file=@var{name}
+@itemx -K @var{name}
+Starts an operation in the middle of an archive. Use in conjunction
+with @option{--extract} (@option{--get}, @option{-x}) or @option{--list} (@option{-t}).
+@end table
+
+@cindex Middle of the archive, starting in the
+If a previous attempt to extract files failed due to lack of disk
+space, you can use @option{--starting-file=@var{name}} (@option{-K
+@var{name}}) to start extracting only after member @var{name} of the
+archive. This assumes, of course, that there is now free space, or
+that you are now extracting into a different file system. (You could
+also choose to suspend @command{tar}, remove unnecessary files from
+the file system, and then restart the same @command{tar} operation.
+In this case, @option{--starting-file} is not necessary.
+@xref{Incremental Dumps}, @xref{interactive}, and @ref{exclude}.)
+
+@node Same Order
+@unnumberedsubsubsec Same Order
+
+@table @option
+@cindex Large lists of file names on small machines
+@opindex same-order
+@opindex preserve-order
+@item --same-order
+@itemx --preserve-order
+@itemx -s
+To process large lists of file names on machines with small amounts of
+memory. Use in conjunction with @option{--compare} (@option{--diff},
+@option{-d}), @option{--list} (@option{-t}) or @option{--extract}
+(@option{--get}, @option{-x}).
+@end table
+
+The @option{--same-order} (@option{--preserve-order}, @option{-s}) option tells @command{tar} that the list of file
+names to be listed or extracted is sorted in the same order as the
+files in the archive. This allows a large list of names to be used,
+even on a small machine that would not otherwise be able to hold all
+the names in memory at the same time. Such a sorted list can easily be
+created by running @samp{tar -t} on the archive and editing its output.
+
+This option is probably never needed on modern computer systems.
+
+@node backup
+@section Backup options
+
+@cindex backup options
+
+@GNUTAR{} offers options for making backups of files
+before writing new versions. These options control the details of
+these backups. They may apply to the archive itself before it is
+created or rewritten, as well as individual extracted members. Other
+@acronym{GNU} programs (@command{cp}, @command{install}, @command{ln},
+and @command{mv}, for example) offer similar options.
+
+Backup options may prove unexpectedly useful when extracting archives
+containing many members having identical name, or when extracting archives
+on systems having file name limitations, making different members appear
+has having similar names through the side-effect of name truncation.
+(This is true only if we have a good scheme for truncated backup names,
+which I'm not sure at all: I suspect work is needed in this area.)
+When any existing file is backed up before being overwritten by extraction,
+then clashing files are automatically be renamed to be unique, and the
+true name is kept for only the last file of a series of clashing files.
+By using verbose mode, users may track exactly what happens.
+
+At the detail level, some decisions are still experimental, and may
+change in the future, we are waiting comments from our users. So, please
+do not learn to depend blindly on the details of the backup features.
+For example, currently, directories themselves are never renamed through
+using these options, so, extracting a file over a directory still has
+good chances to fail. Also, backup options apply to created archives,
+not only to extracted members. For created archives, backups will not
+be attempted when the archive is a block or character device, or when it
+refers to a remote file.
+
+For the sake of simplicity and efficiency, backups are made by renaming old
+files prior to creation or extraction, and not by copying. The original
+name is restored if the file creation fails. If a failure occurs after a
+partial extraction of a file, both the backup and the partially extracted
+file are kept.
+
+@table @samp
+@item --backup[=@var{method}]
+@opindex backup
+@vindex VERSION_CONTROL
+@cindex backups
+Back up files that are about to be overwritten or removed.
+Without this option, the original versions are destroyed.
+
+Use @var{method} to determine the type of backups made.
+If @var{method} is not specified, use the value of the @env{VERSION_CONTROL}
+environment variable. And if @env{VERSION_CONTROL} is not set,
+use the @samp{existing} method.
+
+@vindex version-control @r{Emacs variable}
+This option corresponds to the Emacs variable @samp{version-control};
+the same values for @var{method} are accepted as in Emacs. This option
+also allows more descriptive names. The valid @var{method}s are:
+
+@table @samp
+@item t
+@itemx numbered
+@cindex numbered @r{backup method}
+Always make numbered backups.
+
+@item nil
+@itemx existing
+@cindex existing @r{backup method}
+Make numbered backups of files that already have them, simple backups
+of the others.
+
+@item never
+@itemx simple
+@cindex simple @r{backup method}
+Always make simple backups.
+
+@end table
+
+@item --suffix=@var{suffix}
+@opindex suffix
+@cindex backup suffix
+@vindex SIMPLE_BACKUP_SUFFIX
+Append @var{suffix} to each backup file made with @option{--backup}. If this
+option is not specified, the value of the @env{SIMPLE_BACKUP_SUFFIX}
+environment variable is used. And if @env{SIMPLE_BACKUP_SUFFIX} is not
+set, the default is @samp{~}, just as in Emacs.
+
+@end table
+
+Some people express the desire to @emph{always} use the @option{--backup}
+option, by defining some kind of alias or script. This is not as easy
+as one may think, due to the fact that old style options should appear first
+and consume arguments a bit unpredictably for an alias or script. But,
+if you are ready to give up using old style options, you may resort to
+using something like (a Bourne shell function here):
+
+@smallexample
+tar () @{ /usr/local/bin/tar --backup $*; @}
+@end smallexample
+
+@node Applications
+@section Notable @command{tar} Usages
+@UNREVISED
+
+@FIXME{Using Unix file linking capability to recreate directory
+structures---linking files into one subdirectory and then
+@command{tar}ring that directory.}
+
+@FIXME{Nice hairy example using absolute-names, newer, etc.}
+
+@findex uuencode
+You can easily use archive files to transport a group of files from
+one system to another: put all relevant files into an archive on one
+computer system, transfer the archive to another system, and extract
+the contents there. The basic transfer medium might be magnetic tape,
+Internet FTP, or even electronic mail (though you must encode the
+archive with @command{uuencode} in order to transport it properly by
+mail). Both machines do not have to use the same operating system, as
+long as they both support the @command{tar} program.
+
+For example, here is how you might copy a directory's contents from
+one disk to another, while preserving the dates, modes, owners and
+link-structure of all the files therein. In this case, the transfer
+medium is a @dfn{pipe}, which is one a Unix redirection mechanism:
+
+@smallexample
+$ @kbd{cd sourcedir; tar -cf - . | (cd targetdir; tar -xf -)}
+@end smallexample
+
+@noindent
+The command also works using short option forms:
+
+@smallexample
+$ @w{@kbd{cd sourcedir; tar --create --file=- . | (cd targetdir; tar --extract --file=-)}}
+@end smallexample
+
+@noindent
+This is one of the easiest methods to transfer a @command{tar} archive.
+
+@node looking ahead
+@section Looking Ahead: The Rest of this Manual
+
+You have now seen how to use all eight of the operations available to
+@command{tar}, and a number of the possible options. The next chapter
+explains how to choose and change file and archive names, how to use
+files to store names of other files which you can then call as
+arguments to @command{tar} (this can help you save time if you expect to
+archive the same list of files a number of times), and so forth.
+@FIXME{in case it's not obvious, i'm making this up in some sense
+based on my limited memory of what the next chapter *really* does. i
+just wanted to flesh out this final section a little bit so i'd
+remember to stick it in here. :-)}
+
+If there are too many files to conveniently list on the command line,
+you can list the names in a file, and @command{tar} will read that file.
+@xref{files}.
+
+There are various ways of causing @command{tar} to skip over some files,
+and not archive them. @xref{Choosing}.
+
+@node Backups
+@chapter Performing Backups and Restoring Files
+@UNREVISED
+
+@GNUTAR{} is distributed along with the scripts
+which the Free Software Foundation uses for performing backups. There
+is no corresponding scripts available yet for doing restoration of
+files. Even if there is a good chance those scripts may be satisfying
+to you, they are not the only scripts or methods available for doing
+backups and restore. You may well create your own, or use more
+sophisticated packages dedicated to that purpose.
+
+Some users are enthusiastic about @code{Amanda} (The Advanced Maryland
+Automatic Network Disk Archiver), a backup system developed by James
+da Silva @file{jds@@cs.umd.edu} and available on many Unix systems.
+This is free software, and it is available at these places:
+
+@smallexample
+http://www.cs.umd.edu/projects/amanda/amanda.html
+ftp://ftp.cs.umd.edu/pub/amanda
+@end smallexample
+
+@FIXME{
+
+Here is a possible plan for a future documentation about the backuping
+scripts which are provided within the @GNUTAR{}
+distribution.
+
+@itemize @bullet
+@item dumps
+ @itemize @minus
+ @item what are dumps
+ @item different levels of dumps
+ @itemize +
+ @item full dump = dump everything
+ @item level 1, level 2 dumps etc
+ A level @var{n} dump dumps everything changed since the last level
+ @var{n}-1 dump (?)
+ @end itemize
+ @item how to use scripts for dumps (ie, the concept)
+ @itemize +
+ @item scripts to run after editing backup specs (details)
+ @end itemize
+ @item Backup Specs, what is it.
+ @itemize +
+ @item how to customize
+ @item actual text of script [/sp/dump/backup-specs]
+ @end itemize
+ @item Problems
+ @itemize +
+ @item rsh doesn't work
+ @item rtape isn't installed
+ @item (others?)
+ @end itemize
+ @item the @option{--incremental} option of tar
+ @item tapes
+ @itemize +
+ @item write protection
+ @item types of media, different sizes and types, useful for different things
+ @item files and tape marks
+ one tape mark between files, two at end.
+ @item positioning the tape
+ MT writes two at end of write,
+ backspaces over one when writing again.
+ @end itemize
+ @end itemize
+@end itemize
+}
+
+This chapter documents both the provided shell scripts and @command{tar}
+options which are more specific to usage as a backup tool.
+
+To @dfn{back up} a file system means to create archives that contain
+all the files in that file system. Those archives can then be used to
+restore any or all of those files (for instance if a disk crashes or a
+file is accidentally deleted). File system @dfn{backups} are also
+called @dfn{dumps}.
+
+@menu
+* Full Dumps:: Using @command{tar} to Perform Full Dumps
+* Incremental Dumps:: Using @command{tar} to Perform Incremental Dumps
+* Backup Levels:: Levels of Backups
+* Backup Parameters:: Setting Parameters for Backups and Restoration
+* Scripted Backups:: Using the Backup Scripts
+* Scripted Restoration:: Using the Restore Script
+@end menu
+
+@node Full Dumps
+@section Using @command{tar} to Perform Full Dumps
+@UNREVISED
+
+@cindex full dumps
+@cindex dumps, full
+
+@cindex corrupted archives
+Full dumps should only be made when no other people or programs
+are modifying files in the file system. If files are modified while
+@command{tar} is making the backup, they may not be stored properly in
+the archive, in which case you won't be able to restore them if you
+have to. (Files not being modified are written with no trouble, and do
+not corrupt the entire archive.)
+
+You will want to use the @option{--label=@var{archive-label}}
+(@option{-V @var{archive-label}}) option to give the archive a
+volume label, so you can tell what this archive is even if the label
+falls off the tape, or anything like that.
+
+Unless the file system you are dumping is guaranteed to fit on
+one volume, you will need to use the @option{--multi-volume} (@option{-M}) option.
+Make sure you have enough tapes on hand to complete the backup.
+
+If you want to dump each file system separately you will need to use
+the @option{--one-file-system} (@option{-l}) option to prevent
+@command{tar} from crossing file system boundaries when storing
+(sub)directories.
+
+The @option{--incremental} (@option{-G}) (@pxref{Incremental Dumps})
+option is not needed, since this is a complete copy of everything in
+the file system, and a full restore from this backup would only be
+done onto a completely
+empty disk.
+
+Unless you are in a hurry, and trust the @command{tar} program (and your
+tapes), it is a good idea to use the @option{--verify} (@option{-W})
+option, to make sure your files really made it onto the dump properly.
+This will also detect cases where the file was modified while (or just
+after) it was being archived. Not all media (notably cartridge tapes)
+are capable of being verified, unfortunately.
+
+@node Incremental Dumps
+@section Using @command{tar} to Perform Incremental Dumps
+
+@dfn{Incremental backup} is a special form of @GNUTAR{} archive that
+stores additional metadata so that exact state of the file system
+can be restored when extracting the archive.
+
+@GNUTAR{} currently offers two options for handling incremental
+backups: @option{--listed-incremental=@var{snapshot-file}} (@option{-g
+@var{snapshot-file}}) and @option{--incremental} (@option{-G}).
+
+@opindex listed-incremental
+The option @option{--listed-incremental} instructs tar to operate on
+an incremental archive with additional metadata stored in a standalone
+file, called a @dfn{snapshot file}. The purpose of this file is to help
+determine which files have been changed, added or deleted since the
+last backup, so that the next incremental backup will contain only
+modified files. The name of the snapshot file is given as an argument
+to the option:
+
+@table @option
+@item --listed-incremental=@var{file}
+@itemx -g @var{file}
+ Handle incremental backups with snapshot data in @var{file}.
+@end table
+
+To create an incremental backup, you would use
+@option{--listed-incremental} together with @option{--create}
+(@pxref{create}). For example:
+
+@smallexample
+$ @kbd{tar --create \
+ --file=archive.1.tar \
+ --listed-incremental=/var/log/usr.snar \
+ /usr}
+@end smallexample
+
+This will create in @file{archive.1.tar} an incremental backup of
+the @file{/usr} file system, storing additional metadata in the file
+@file{/var/log/usr.snar}. If this file does not exist, it will be
+created. The created archive will then be a @dfn{level 0 backup};
+please see the next section for more on backup levels.
+
+Otherwise, if the file @file{/var/log/usr.snar} exists, it
+determines which files are modified. In this case only these files will be
+stored in the archive. Suppose, for example, that after running the
+above command, you delete file @file{/usr/doc/old} and create
+directory @file{/usr/local/db} with the following contents:
+
+@smallexample
+$ @kbd{ls /usr/local/db}
+/usr/local/db/data
+/usr/local/db/index
+@end smallexample
+
+Some time later you create another incremental backup. You will
+then see:
+
+@smallexample
+$ @kbd{tar --create \
+ --file=archive.2.tar \
+ --listed-incremental=/var/log/usr.snar \
+ /usr}
+tar: usr/local/db: Directory is new
+usr/local/db/
+usr/local/db/data
+usr/local/db/index
+@end smallexample
+
+@noindent
+The created archive @file{archive.2.tar} will contain only these
+three members. This archive is called a @dfn{level 1 backup}. Notice
+that @file{/var/log/usr.snar} will be updated with the new data, so if
+you plan to create more @samp{level 1} backups, it is necessary to
+create a working copy of the snapshot file before running
+@command{tar}. The above example will then be modified as follows:
+
+@smallexample
+$ @kbd{cp /var/log/usr.snar /var/log/usr.snar-1}
+$ @kbd{tar --create \
+ --file=archive.2.tar \
+ --listed-incremental=/var/log/usr.snar-1 \
+ /usr}
+@end smallexample
+
+Incremental dumps depend crucially on time stamps, so the results are
+unreliable if you modify a file's time stamps during dumping (e.g.,
+with the @option{--atime-preserve=replace} option), or if you set the clock
+backwards.
+
+Metadata stored in snapshot files include device numbers, which,
+obviously is supposed to be a non-volatile value. However, it turns
+out that NFS devices have undependable values when an automounter
+gets in the picture. This can lead to a great deal of spurious
+redumping in incremental dumps, so it is somewhat useless to compare
+two NFS devices numbers over time. The solution implemented currently
+is to considers all NFS devices as being equal when it comes to
+comparing directories; this is fairly gross, but there does not seem
+to be a better way to go.
+
+Note that incremental archives use @command{tar} extensions and may
+not be readable by non-@acronym{GNU} versions of the @command{tar} program.
+
+@opindex listed-incremental, using with @option{--extract}
+@opindex extract, using with @option{--listed-incremental}
+To extract from the incremental dumps, use
+@option{--listed-incremental} together with @option{--extract}
+option (@pxref{extracting files}). In this case, @command{tar} does
+not need to access snapshot file, since all the data necessary for
+extraction are stored in the archive itself. So, when extracting, you
+can give whatever argument to @option{--listed-incremental}, the usual
+practice is to use @option{--listed-incremental=/dev/null}.
+Alternatively, you can use @option{--incremental}, which needs no
+arguments. In general, @option{--incremental} (@option{-G}) can be
+used as a shortcut for @option{--listed-incremental} when listing or
+extracting incremental backups (for more information, regarding this
+option, @pxref{incremental-op}).
+
+When extracting from the incremental backup @GNUTAR{} attempts to
+restore the exact state the file system had when the archive was
+created. In particular, it will @emph{delete} those files in the file
+system that did not exist in their directories when the archive was
+created. If you have created several levels of incremental files,
+then in order to restore the exact contents the file system had when
+the last level was created, you will need to restore from all backups
+in turn. Continuing our example, to restore the state of @file{/usr}
+file system, one would do@footnote{Notice, that since both archives
+were created withouth @option{-P} option (@pxref{absolute}), these
+commands should be run from the root file system.}:
+
+@smallexample
+$ @kbd{tar --extract \
+ --listed-incremental=/dev/null \
+ --file archive.1.tar}
+$ @kbd{tar --extract \
+ --listed-incremental=/dev/null \
+ --file archive.2.tar}
+@end smallexample
+
+To list the contents of an incremental archive, use @option{--list}
+(@pxref{list}), as usual. To obtain more information about the
+archive, use @option{--listed-incremental} or @option{--incremental}
+combined with two @option{--verbose} options@footnote{Two
+@option{--verbose} options were selected to avoid breaking usual
+verbose listing output (@option{--list --verbose}) when using in
+scripts.
+
+@opindex incremental, using with @option{--list}
+@opindex listed-incremental, using with @option{--list}
+@opindex list, using with @option{--incremental}
+@opindex list, using with @option{--listed-incremental}
+Versions of @GNUTAR{} up to 1.15.1 used to dump verbatim binary
+contents of the DUMPDIR header (with terminating nulls) when
+@option{--incremental} or @option{--listed-incremental} option was
+given, no matter what the verbosity level. This behavior, and,
+especially, the binary output it produced were considered incovenient
+and were changed in version 1.16}:
+
+@smallexample
+@kbd{tar --list --incremental --verbose --verbose archive.tar}
+@end smallexample
+
+This command will print, for each directory in the archive, the list
+of files in that directory at the time the archive was created. This
+information is put out in a format which is both human-readable and
+unambiguous for a program: each file name is printed as
+
+@smallexample
+@var{x} @var{file}
+@end smallexample
+
+@noindent
+where @var{x} is a letter describing the status of the file: @samp{Y}
+if the file is present in the archive, @samp{N} if the file is not
+included in the archive, or a @samp{D} if the file is a directory (and
+is included in the archive).@FIXME-xref{dumpdir format}. Each such
+line is terminated by a newline character. The last line is followed
+by an additional newline to indicate the end of the data.
+
+@anchor{incremental-op}The option @option{--incremental} (@option{-G})
+gives the same behavior as @option{--listed-incremental} when used
+with @option{--list} and @option{--extract} options. When used with
+@option{--create} option, it creates an incremental archive without
+creating snapshot file. Thus, it is impossible to create several
+levels of incremental backups with @option{--incremental} option.
+
+@node Backup Levels
+@section Levels of Backups
+
+An archive containing all the files in the file system is called a
+@dfn{full backup} or @dfn{full dump}. You could insure your data by
+creating a full dump every day. This strategy, however, would waste a
+substantial amount of archive media and user time, as unchanged files
+are daily re-archived.
+
+It is more efficient to do a full dump only occasionally. To back up
+files between full dumps, you can use @dfn{incremental dumps}. A @dfn{level
+one} dump archives all the files that have changed since the last full
+dump.
+
+A typical dump strategy would be to perform a full dump once a week,
+and a level one dump once a day. This means some versions of files
+will in fact be archived more than once, but this dump strategy makes
+it possible to restore a file system to within one day of accuracy by
+only extracting two archives---the last weekly (full) dump and the
+last daily (level one) dump. The only information lost would be in
+files changed or created since the last daily backup. (Doing dumps
+more than once a day is usually not worth the trouble).
+
+@GNUTAR{} comes with scripts you can use to do full
+and level-one (actually, even level-two and so on) dumps. Using
+scripts (shell programs) to perform backups and restoration is a
+convenient and reliable alternative to typing out file name lists
+and @command{tar} commands by hand.
+
+Before you use these scripts, you need to edit the file
+@file{backup-specs}, which specifies parameters used by the backup
+scripts and by the restore script. This file is usually located
+in @file{/etc/backup} directory. @xref{Backup Parameters}, for its
+detailed description. Once the backup parameters are set, you can
+perform backups or restoration by running the appropriate script.
+
+The name of the backup script is @code{backup}. The name of the
+restore script is @code{restore}. The following sections describe
+their use in detail.
+
+@emph{Please Note:} The backup and restoration scripts are
+designed to be used together. While it is possible to restore files by
+hand from an archive which was created using a backup script, and to create
+an archive by hand which could then be extracted using the restore script,
+it is easier to use the scripts. @xref{Incremental Dumps}, before
+making such an attempt.
+
+@node Backup Parameters
+@section Setting Parameters for Backups and Restoration
+
+The file @file{backup-specs} specifies backup parameters for the
+backup and restoration scripts provided with @command{tar}. You must
+edit @file{backup-specs} to fit your system configuration and schedule
+before using these scripts.
+
+Syntactically, @file{backup-specs} is a shell script, containing
+mainly variable assignments. However, any valid shell construct
+is allowed in this file. Particularly, you may wish to define
+functions within that script (e.g., see @code{RESTORE_BEGIN} below).
+For more information about shell script syntax, please refer to
+@url{http://www.opengroup.org/onlinepubs/009695399/utilities/xcu_chap02.html#ta
+g_02, the definition of the Shell Command Language}. See also
+@ref{Top,,Bash Features,bashref,Bash Reference Manual}.
+
+The shell variables controlling behavior of @code{backup} and
+@code{restore} are described in the following subsections.
+
+@menu
+* General-Purpose Variables::
+* Magnetic Tape Control::
+* User Hooks::
+* backup-specs example:: An Example Text of @file{Backup-specs}
+@end menu
+
+@node General-Purpose Variables
+@subsection General-Purpose Variables
+
+@defvr {Backup variable} ADMINISTRATOR
+The user name of the backup administrator. @code{Backup} scripts
+sends a backup report to this address.
+@end defvr
+
+@defvr {Backup variable} BACKUP_HOUR
+The hour at which the backups are done. This can be a number from 0
+to 23, or the time specification in form @var{hours}:@var{minutes},
+or the string @samp{now}.
+
+This variable is used by @code{backup}. Its value may be overridden
+using @option{--time} option (@pxref{Scripted Backups}).
+@end defvr
+
+@defvr {Backup variable} TAPE_FILE
+
+The device @command{tar} writes the archive to. If @var{TAPE_FILE}
+is a remote archive (@pxref{remote-dev}), backup script will suppose
+that your @command{mt} is able to access remote devices. If @var{RSH}
+(@pxref{RSH}) is set, @option{--rsh-command} option will be added to
+invocations of @command{mt}.
+@end defvr
+
+@defvr {Backup variable} BLOCKING
+
+The blocking factor @command{tar} will use when writing the dump archive.
+@xref{Blocking Factor}.
+@end defvr
+
+@defvr {Backup variable} BACKUP_DIRS
+
+A list of file systems to be dumped (for @code{backup}), or restored
+(for @code{restore}). You can include any directory
+name in the list --- subdirectories on that file system will be
+included, regardless of how they may look to other networked machines.
+Subdirectories on other file systems will be ignored.
+
+The host name specifies which host to run @command{tar} on, and should
+normally be the host that actually contains the file system. However,
+the host machine must have @GNUTAR{} installed, and
+must be able to access the directory containing the backup scripts and
+their support files using the same file name that is used on the
+machine where the scripts are run (ie. what @command{pwd} will print
+when in that directory on that machine). If the host that contains
+the file system does not have this capability, you can specify another
+host as long as it can access the file system through NFS.
+
+If the list of file systems is very long you may wish to put it
+in a separate file. This file is usually named
+@file{/etc/backup/dirs}, but this name may be overridden in
+@file{backup-specs} using @code{DIRLIST} variable.
+@end defvr
+
+@defvr {Backup variable} DIRLIST
+
+A path to the file containing the list of the file systems to backup
+or restore. By default it is @file{/etc/backup/dirs}.
+@end defvr
+
+@defvr {Backup variable} BACKUP_FILES
+
+A list of individual files to be dumped (for @code{backup}), or restored
+(for @code{restore}). These should be accessible from the machine on
+which the backup script is run.
+
+If the list of file systems is very long you may wish to store it
+in a separate file. This file is usually named
+@file{/etc/backup/files}, but this name may be overridden in
+@file{backup-specs} using @code{FILELIST} variable.
+@end defvr
+
+@defvr {Backup variable} FILELIST
+
+A path to the file containing the list of the individual files to backup
+or restore. By default it is @file{/etc/backup/files}.
+@end defvr
+
+@defvr {Backup variable} MT
+
+Full file name of @command{mt} binary.
+@end defvr
+
+@defvr {Backup variable} RSH
+@anchor{RSH}
+Full file name of @command{rsh} binary or its equivalent. You may wish to
+set it to @code{ssh}, to improve security. In this case you will have
+to use public key authentication.
+@end defvr
+
+@defvr {Backup variable} RSH_COMMAND
+
+Full file name of @command{rsh} binary on remote mashines. This will
+be passed via @option{--rsh-command} option to the remote invocation
+of @GNUTAR{}.
+@end defvr
+
+@defvr {Backup variable} VOLNO_FILE
+
+Name of temporary file to hold volume numbers. This needs to be accessible
+by all the machines which have file systems to be dumped.
+@end defvr
+
+@defvr {Backup variable} XLIST
+
+Name of @dfn{exclude file list}. An @dfn{exclude file list} is a file
+located on the remote machine and containing the list of files to
+be excluded from the backup. Exclude file lists are searched in
+/etc/tar-backup directory. A common use for exclude file lists
+is to exclude files containing security-sensitive information
+(e.g., @file{/etc/shadow} from backups).
+
+This variable affects only @code{backup}.
+@end defvr
+
+@defvr {Backup variable} SLEEP_TIME
+
+Time to sleep between dumps of any two successive file systems
+
+This variable affects only @code{backup}.
+@end defvr
+
+@defvr {Backup variable} DUMP_REMIND_SCRIPT
+
+Script to be run when it's time to insert a new tape in for the next
+volume. Administrators may want to tailor this script for their site.
+If this variable isn't set, @GNUTAR{} will display its built-in prompt
+@FIXME-xref{describe it somewhere!}, and will expect confirmation from
+the console.
+@end defvr
+
+@defvr {Backup variable} SLEEP_MESSAGE
+
+Message to display on the terminal while waiting for dump time. Usually
+this will just be some literal text.
+@end defvr
+
+@defvr {Backup variable} TAR
+
+Full file name of the @GNUTAR{} executable. If this is not set, backup
+scripts will search @command{tar} in the current shell path.
+@end defvr
+
+@node Magnetic Tape Control
+@subsection Magnetic Tape Control
+
+Backup scripts access tape device using special @dfn{hook functions}.
+These functions take a single argument -- the name of the tape
+device. Their names are kept in the following variables:
+
+@defvr {Backup variable} MT_BEGIN
+The name of @dfn{begin} function. This function is called before
+accessing the drive. By default it retensions the tape:
+
+@smallexample
+MT_BEGIN=mt_begin
+
+mt_begin() @{
+ mt -f "$1" retension
+@}
+@end smallexample
+@end defvr
+
+@defvr {Backup variable} MT_REWIND
+The name of @dfn{rewind} function. The default definition is as
+follows:
+
+@smallexample
+MT_REWIND=mt_rewind
+
+mt_rewind() @{
+ mt -f "$1" rewind
+@}
+@end smallexample
+
+@end defvr
+
+@defvr {Backup variable} MT_OFFLINE
+The name of the function switching the tape off line. By default
+it is defined as follows:
+
+@smallexample
+MT_OFFLINE=mt_offline
+
+mt_offline() @{
+ mt -f "$1" offl
+@}
+@end smallexample
+@end defvr
+
+@defvr {Backup variable} MT_STATUS
+The name of the function used to obtain the status of the archive device,
+including error count. Default definition:
+
+@smallexample
+MT_STATUS=mt_status
+
+mt_status() @{
+ mt -f "$1" status
+@}
+@end smallexample
+@end defvr
+
+@node User Hooks
+@subsection User Hooks
+
+@dfn{User hooks} are shell functions executed before and after
+each @command{tar} invocation. Thus, there are @dfn{backup
+hooks}, which are executed before and after dumping each file
+system, and @dfn{restore hooks}, executed before and
+after restoring a file system. Each user hook is a shell function
+taking four arguments:
+
+@deffn {User Hook Function} hook @var{level} @var{host} @var{fs} @var{fsname}
+Its arguments are:
+
+@table @var
+@item level
+Current backup or restore level.
+
+@item host
+Name or IP address of the host machine being dumped or restored.
+
+@item fs
+Full path name to the file system being dumped or restored.
+
+@item fsname
+File system name with directory separators replaced with colons. This
+is useful, e.g., for creating unique files.
+@end table
+@end deffn
+
+Following variables keep the names of user hook functions
+
+@defvr {Backup variable} DUMP_BEGIN
+Dump begin function. It is executed before dumping the file system.
+@end defvr
+
+@defvr {Backup variable} DUMP_END
+Executed after dumping the file system.
+@end defvr
+
+@defvr {Backup variable} RESTORE_BEGIN
+Executed before restoring the file system.
+@end defvr
+
+@defvr {Backup variable} RESTORE_END
+Executed after restoring the file system.
+@end defvr
+
+@node backup-specs example
+@subsection An Example Text of @file{Backup-specs}
+
+The following is an example of @file{backup-specs}:
+
+@smallexample
+# site-specific parameters for file system backup.
+
+ADMINISTRATOR=friedman
+BACKUP_HOUR=1
+TAPE_FILE=/dev/nrsmt0
+
+# Use @code{ssh} instead of the less secure @code{rsh}
+RSH=/usr/bin/ssh
+RSH_COMMAND=/usr/bin/ssh
+
+# Override MT_STATUS function:
+my_status() @{
+ mts -t $TAPE_FILE
+@}
+MT_STATUS=my_status
+
+# Disable MT_OFFLINE function
+MT_OFFLINE=:
+
+BLOCKING=124
+BACKUP_DIRS="
+ albert:/fs/fsf
+ apple-gunkies:/gd
+ albert:/fs/gd2
+ albert:/fs/gp
+ geech:/usr/jla
+ churchy:/usr/roland
+ albert:/
+ albert:/usr
+ apple-gunkies:/
+ apple-gunkies:/usr
+ gnu:/hack
+ gnu:/u
+ apple-gunkies:/com/mailer/gnu
+ apple-gunkies:/com/archive/gnu"
+
+BACKUP_FILES="/com/mailer/aliases /com/mailer/league*[a-z]"
+
+@end smallexample
+
+@node Scripted Backups
+@section Using the Backup Scripts
+
+The syntax for running a backup script is:
+
+@smallexample
+backup --level=@var{level} --time=@var{time}
+@end smallexample
+
+The @option{level} option requests the dump level. Thus, to produce
+a full dump, specify @code{--level=0} (this is the default, so
+@option{--level} may be omitted if its value is @code{0}).
+@footnote{For backward compatibility, the @code{backup} will also
+try to deduce the requested dump level from the name of the
+script itself. If the name consists of a string @samp{level-}
+followed by a single decimal digit, that digit is taken as
+the dump level number. Thus, you may create a link from @code{backup}
+to @code{level-1} and then run @code{level-1} whenever you need to
+create a level one dump.}
+
+The @option{--time} option determines when should the backup be
+run. @var{Time} may take three forms:
+
+@table @asis
+@item @var{hh}:@var{mm}
+
+The dump must be run at @var{hh} hours @var{mm} minutes.
+
+@item @var{hh}
+
+The dump must be run at @var{hh} hours
+
+@item now
+
+The dump must be run immediately.
+@end table
+
+You should start a script with a tape or disk mounted. Once you
+start a script, it prompts you for new tapes or disks as it
+needs them. Media volumes don't have to correspond to archive
+files --- a multi-volume archive can be started in the middle of a
+tape that already contains the end of another multi-volume archive.
+The @code{restore} script prompts for media by its archive volume,
+so to avoid an error message you should keep track of which tape
+(or disk) contains which volume of the archive (@pxref{Scripted
+Restoration}).
+
+The backup scripts write two files on the file system. The first is a
+record file in @file{/etc/tar-backup/}, which is used by the scripts
+to store and retrieve information about which files were dumped. This
+file is not meant to be read by humans, and should not be deleted by
+them. @xref{Snapshot Files}, for a more detailed explanation of this
+file.
+
+The second file is a log file containing the names of the file systems
+and files dumped, what time the backup was made, and any error
+messages that were generated, as well as how much space was left in
+the media volume after the last volume of the archive was written.
+You should check this log file after every backup. The file name is
+@file{log-@var{mm-dd-yyyy}-level-@var{n}}, where @var{mm-dd-yyyy}
+represents current date, and @var{n} represents current dump level number.
+
+The script also prints the name of each system being dumped to the
+standard output.
+
+Following is the full list of options accepted by @code{backup}
+script:
+
+@table @option
+@item -l @var{level}
+@itemx --level=@var{level}
+Do backup level @var{level} (default 0).
+
+@item -f
+@itemx --force
+Force backup even if today's log file already exists.
+
+@item -v[@var{level}]
+@itemx --verbose[=@var{level}]
+Set verbosity level. The higher the level is, the more debugging
+information will be output during execution. Devault @var{level}
+is 100, which means the highest debugging level.
+
+@item -t @var{start-time}
+@itemx --time=@var{start-time}
+Wait till @var{time}, then do backup.
+
+@item -h
+@itemx --help
+Display short help message and exit.
+
+@item -V
+@itemx --version
+Display information about the program's name, version, origin and legal
+status, all on standard output, and then exit successfully.
+@end table
+
+
+@node Scripted Restoration
+@section Using the Restore Script
+
+To restore files that were archived using a scripted backup, use the
+@code{restore} script. Its usage is quite straightforward. In the
+simplest form, invoke @code{restore --all}, it will
+then restore all the file systems and files specified in
+@file{backup-specs} (@pxref{General-Purpose Variables,BACKUP_DIRS}).
+
+You may select the file systems (and/or files) to restore by
+giving @code{restore} list of @dfn{patterns} in its command
+line. For example, running
+
+@smallexample
+restore 'albert:*'
+@end smallexample
+
+@noindent
+will restore all file systems on the machine @samp{albert}. A more
+complicated example:
+
+@smallexample
+restore 'albert:*' '*:/var'
+@end smallexample
+
+@noindent
+This command will restore all file systems on the machine @samp{albert}
+as well as @file{/var} file system on all machines.
+
+By default @code{restore} will start restoring files from the lowest
+available dump level (usually zero) and will continue through
+all available dump levels. There may be situations where such a
+thorough restore is not necessary. For example, you may wish to
+restore only files from the recent level one backup. To do so,
+use @option{--level} option, as shown in the example below:
+
+@smallexample
+restore --level=1
+@end smallexample
+
+The full list of options accepted by @code{restore} follows:
+
+@table @option
+@item -a
+@itemx --all
+Restore all file systems and files specified in @file{backup-specs}
+
+@item -l @var{level}
+@itemx --level=@var{level}
+Start restoring from the given backup level, instead of the default 0.
+
+@item -v[@var{level}]
+@itemx --verbose[=@var{level}]
+Set verbosity level. The higher the level is, the more debugging
+information will be output during execution. Devault @var{level}
+is 100, which means the highest debugging level.
+
+@item -h
+@itemx --help
+Display short help message and exit.
+
+@item -V
+@itemx --version
+Display information about the program's name, version, origin and legal
+status, all on standard output, and then exit successfully.
+@end table
+
+You should start the restore script with the media containing the
+first volume of the archive mounted. The script will prompt for other
+volumes as they are needed. If the archive is on tape, you don't need
+to rewind the tape to to its beginning---if the tape head is
+positioned past the beginning of the archive, the script will rewind
+the tape as needed. @FIXME-xref{Media, for a discussion of tape
+positioning.}
+
+@quotation
+@strong{Warning:} The script will delete files from the active file
+system if they were not in the file system when the archive was made.
+@end quotation
+
+@xref{Incremental Dumps}, for an explanation of how the script makes
+that determination.
+
+@node Choosing
+@chapter Choosing Files and Names for @command{tar}
+@UNREVISED
+
+@FIXME{Melissa (still) Doesn't Really Like This ``Intro'' Paragraph!!!}
+
+Certain options to @command{tar} enable you to specify a name for your
+archive. Other options let you decide which files to include or exclude
+from the archive, based on when or whether files were modified, whether
+the file names do or don't match specified patterns, or whether files
+are in specified directories.
@menu
-* Additional Information::
-* Interactive Operation::
+* file:: Choosing the Archive's Name
+* Selecting Archive Members::
+* files:: Reading Names from a File
+* exclude:: Excluding Some Files
+* Wildcards::
+* after:: Operating Only on New Files
+* recurse:: Descending into Directories
+* one:: Crossing File System Boundaries
@end menu
-@node Additional Information, Interactive Operation, User Interaction, User Interaction
-@section Progress and Status Information
-@cindex Progress information
-@cindex Status information
-@cindex Information on progress and status of operations
-@cindex Verbose operation
-@cindex Record number where error occured
-@cindex Error message, record number of
-@cindex Version of the @code{tar} program
-
-Typically, @code{tar} performs most operations without reporting any
-information to the user except error messages. If you have
-encountered a problem when operating on an archive, however, you may
-need more information than just an error message in order to solve the
-problem. The following options can be helpful diagnostic tools.
-
-When used with most operations, @samp{+verbose} causes @code{tar} to
-print the file names of the files or archive members it is operating
-on. When used with @samp{tar +list}, the verbose option causes
-@code{tar} to print out an @samp{ls -l} type listing of the files in
-the archive.
-
-Verbose output appears on the standard output except when an archive
-is being written to the standard output (as with @samp{tar +create
-+file=- +verbose}). In that case @code{tar} writes verbose output to
-the standard error stream.
+@node file
+@section Choosing and Naming Archive Files
+@UNREVISED
+
+@FIXME{should the title of this section actually be, "naming an
+archive"?}
+
+@cindex Naming an archive
+@cindex Archive Name
+@cindex Choosing an archive file
+@cindex Where is the archive?
+By default, @command{tar} uses an archive file name that was compiled when
+it was built on the system; usually this name refers to some physical
+tape drive on the machine. However, the person who installed @command{tar}
+on the system may not set the default to a meaningful value as far as
+most users are concerned. As a result, you will usually want to tell
+@command{tar} where to find (or create) the archive. The @option{--file=@var{archive-name}} (@option{-f @var{archive-name}})
+option allows you to either specify or name a file to use as the archive
+instead of the default archive file location.
+
+@table @option
+@opindex file, short description
+@item --file=@var{archive-name}
+@itemx -f @var{archive-name}
+Name the archive to create or operate on. Use in conjunction with
+any operation.
+@end table
+
+For example, in this @command{tar} command,
+
+@smallexample
+$ @kbd{tar -cvf collection.tar blues folk jazz}
+@end smallexample
+
+@noindent
+@file{collection.tar} is the name of the archive. It must directly
+follow the @option{-f} option, since whatever directly follows @option{-f}
+@emph{will} end up naming the archive. If you neglect to specify an
+archive name, you may end up overwriting a file in the working directory
+with the archive you create since @command{tar} will use this file's name
+for the archive name.
+
+An archive can be saved as a file in the file system, sent through a
+pipe or over a network, or written to an I/O device such as a tape,
+floppy disk, or CD write drive.
+
+@cindex Writing new archives
+@cindex Archive creation
+If you do not name the archive, @command{tar} uses the value of the
+environment variable @env{TAPE} as the file name for the archive. If
+that is not available, @command{tar} uses a default, compiled-in archive
+name, usually that for tape unit zero (ie. @file{/dev/tu00}).
+@command{tar} always needs an archive name.
+
+If you use @file{-} as an @var{archive-name}, @command{tar} reads the
+archive from standard input (when listing or extracting files), or
+writes it to standard output (when creating an archive). If you use
+@file{-} as an @var{archive-name} when modifying an archive,
+@command{tar} reads the original archive from its standard input and
+writes the entire new archive to its standard output.
+
+@FIXME{might want a different example here; this is already used in
+"notable tar usages".}
+
+@smallexample
+$ @kbd{cd sourcedir; tar -cf - . | (cd targetdir; tar -xf -)}
+@end smallexample
+
+@FIXME{help!}
+
+@cindex Standard input and output
+@cindex tar to standard input and output
+@anchor{remote-dev}
+To specify an archive file on a device attached to a remote machine,
+use the following:
+
+@smallexample
+@kbd{--file=@var{hostname}:/@var{dev}/@var{file name}}
+@end smallexample
+
+@noindent
+@command{tar} will complete the remote connection, if possible, and
+prompt you for a username and password. If you use
+@option{--file=@@@var{hostname}:/@var{dev}/@var{file name}}, @command{tar}
+will complete the remote connection, if possible, using your username
+as the username on the remote machine.
+
+@cindex Local and remote archives
+@anchor{local and remote archives}
+If the archive file name includes a colon (@samp{:}), then it is assumed
+to be a file on another machine. If the archive file is
+@samp{@var{user}@@@var{host}:@var{file}}, then @var{file} is used on the
+host @var{host}. The remote host is accessed using the @command{rsh}
+program, with a username of @var{user}. If the username is omitted
+(along with the @samp{@@} sign), then your user name will be used.
+(This is the normal @command{rsh} behavior.) It is necessary for the
+remote machine, in addition to permitting your @command{rsh} access, to
+have the @file{rmt} program installed (This command is included in
+the @GNUTAR{} distribution and by default is installed under
+@file{@var{prefix}/libexec/rmt}, were @var{prefix} means your
+installation prefix). If you need to use a file whose name includes a
+colon, then the remote tape drive behavior
+can be inhibited by using the @option{--force-local} option.
+
+@FIXME{i know we went over this yesterday, but bob (and now i do again,
+too) thinks it's out of the middle of nowhere. it doesn't seem to tie
+into what came before it well enough <<i moved it now, is it better
+here?>>. bob also comments that if Amanda isn't free software, we
+shouldn't mention it..}
+
+When the archive is being created to @file{/dev/null}, @GNUTAR{}
+tries to minimize input and output operations. The
+Amanda backup system, when used with @GNUTAR{}, has
+an initial sizing pass which uses this feature.
+
+@node Selecting Archive Members
+@section Selecting Archive Members
+@cindex Specifying files to act on
+@cindex Specifying archive members
+
+@dfn{File Name arguments} specify which files in the file system
+@command{tar} operates on, when creating or adding to an archive, or which
+archive members @command{tar} operates on, when reading or deleting from
+an archive. @xref{Operations}.
+
+To specify file names, you can include them as the last arguments on
+the command line, as follows:
+@smallexample
+@kbd{tar} @var{operation} [@var{option1} @var{option2} @dots{}] [@var{file name-1} @var{file name-2} @dots{}]
+@end smallexample
+
+If a file name begins with dash (@samp{-}), preceede it with
+@option{--add-file} option to preventit from being treated as an
+option.
+
+If you specify a directory name as a file name argument, all the files
+in that directory are operated on by @command{tar}.
+
+If you do not specify files when @command{tar} is invoked with
+@option{--create} (@option{-c}), @command{tar} operates on all the non-directory files in
+the working directory. If you specify either @option{--list} (@option{-t}) or
+@option{--extract} (@option{--get}, @option{-x}), @command{tar} operates on all the archive members in the
+archive. If you specify any operation other than one of these three,
+@command{tar} does nothing.
+
+By default, @command{tar} takes file names from the command line. However,
+there are other ways to specify file or member names, or to modify the
+manner in which @command{tar} selects the files or members upon which to
+operate. @FIXME{add xref here}In general, these methods work both for
+specifying the names of files and archive members.
+
+@node files
+@section Reading Names from a File
+
+@cindex Reading file names from a file
+@cindex Lists of file names
+@cindex File Name arguments, alternatives
+Instead of giving the names of files or archive members on the command
+line, you can put the names into a file, and then use the
+@option{--files-from=@var{file-of-names}} (@option{-T @var{file-of-names}}) option to @command{tar}. Give the name of the file
+which contains the list of files to include as the argument to
+@option{--files-from}. In the list, the file names should be separated by
+newlines. You will frequently use this option when you have generated
+the list of files to archive with the @command{find} utility.
+
+@table @option
+@opindex files-from
+@item --files-from=@var{file name}
+@itemx -T @var{file name}
+Get names to extract or create from file @var{file name}.
+@end table
+
+If you give a single dash as a file name for @option{--files-from}, (i.e.,
+you specify either @code{--files-from=-} or @code{-T -}), then the file
+names are read from standard input.
+
+Unless you are running @command{tar} with @option{--create}, you can not use
+both @code{--files-from=-} and @code{--file=-} (@code{-f -}) in the same
+command.
+
+Any number of @option{-T} options can be given in the command line.
+
+@FIXME{add bob's example, from his message on 2-10-97}
+
+The following example shows how to use @command{find} to generate a list of
+files smaller than 400K in length and put that list into a file
+called @file{small-files}. You can then use the @option{-T} option to
+@command{tar} to specify the files from that file, @file{small-files}, to
+create the archive @file{little.tgz}. (The @option{-z} option to
+@command{tar} compresses the archive with @command{gzip}; @pxref{gzip} for
+more information.)
+
+@smallexample
+$ @kbd{find . -size -400 -print > small-files}
+$ @kbd{tar -c -v -z -T small-files -f little.tgz}
+@end smallexample
+
+@noindent
+In the file list given by @option{-T} option, any file name beginning
+with @samp{-} character is considered a @command{tar} option and is
+processed accordingly.@footnote{Versions of @GNUTAR{} up to 1.15.1
+recognized only @option{-C} option in file lists, and only if the
+option and its argument occupied two consecutive lines.} For example,
+the common use of this feature is to change to another directory by
+specifying @option{-C} option:
+
+@smallexample
+@group
+$ @kbd{cat list}
+-C/etc
+passwd
+hosts
+-C/lib
+libc.a
+$ @kbd{tar -c -f foo.tar --files-from list}
+@end group
+@end smallexample
+
+@noindent
+In this example, @command{tar} will first switch to @file{/etc}
+directory and add files @file{passwd} and @file{hosts} to the
+archive. Then it will change to @file{/lib} directory and will archive
+the file @file{libc.a}. Thus, the resulting archive @file{foo.tar} will
+contain:
+
+@smallexample
+@group
+$ @kbd{tar tf foo.tar}
+passwd
+hosts
+libc.a
+@end group
+@end smallexample
+
+@noindent
+@opindex directory, using in @option{--files-from} argument
+Notice that the option parsing algorithm used with @option{-T} is
+stricter than the one used by shell. Namely, when specifying option
+arguments, you should observe the following rules:
+
+@itemize @bullet
+@item
+When using short (single-letter) option form, its argument must
+immediately follow the option letter, without any intervening
+whitespace. For example: @code{-Cdir}.
+
+@item
+When using long option form, the option argument must be separated
+from the option by a single equal sign. No whitespace is allowed on
+any side of the equal sign. For example: @code{--directory=dir}.
+
+@item
+For both short and long option forms, the option argument can be given
+on the next line after the option name, e.g.:
+
+@smallexample
+@group
+--directory
+dir
+@end group
+@end smallexample
+
+@noindent
+and
+
+@smallexample
+@group
+-C
+dir
+@end group
+@end smallexample
+@end itemize
+
+@opindex add-file
+If you happen to have a file whose name starts with @samp{-},
+precede it with @option{--add-file} option to prevent it from
+being recognized as an option. For example: @code{--add-file --my-file}.
+
+@menu
+* nul::
+@end menu
+
+@node nul
+@subsection @code{NUL} Terminated File Names
+
+@cindex File names, terminated by @code{NUL}
+@cindex @code{NUL} terminated file names
+The @option{--null} option causes @option{--files-from=@var{file-of-names}} (@option{-T @var{file-of-names}}) to read file
+names terminated by a @code{NUL} instead of a newline, so files whose
+names contain newlines can be archived using @option{--files-from}.
+
+@table @option
+@opindex null
+@item --null
+Only consider @code{NUL} terminated file names, instead of files that
+terminate in a newline.
+@end table
+
+The @option{--null} option is just like the one in @acronym{GNU}
+@command{xargs} and @command{cpio}, and is useful with the
+@option{-print0} predicate of @acronym{GNU} @command{find}. In
+@command{tar}, @option{--null} also disables special handling for
+file names that begin with dash.
+
+This example shows how to use @command{find} to generate a list of files
+larger than 800K in length and put that list into a file called
+@file{long-files}. The @option{-print0} option to @command{find} is just
+like @option{-print}, except that it separates files with a @code{NUL}
+rather than with a newline. You can then run @command{tar} with both the
+@option{--null} and @option{-T} options to specify that @command{tar} get the
+files from that file, @file{long-files}, to create the archive
+@file{big.tgz}. The @option{--null} option to @command{tar} will cause
+@command{tar} to recognize the @code{NUL} separator between files.
+
+@smallexample
+$ @kbd{find . -size +800 -print0 > long-files}
+$ @kbd{tar -c -v --null --files-from=long-files --file=big.tar}
+@end smallexample
+
+@FIXME{say anything else here to conclude the section?}
+
+@node exclude
+@section Excluding Some Files
+@UNREVISED
+
+@cindex File names, excluding files by
+@cindex Excluding files by name and pattern
+@cindex Excluding files by file system
+To avoid operating on files whose names match a particular pattern,
+use the @option{--exclude} or @option{--exclude-from} options.
+
+@table @option
+@opindex exclude
+@item --exclude=@var{pattern}
+Causes @command{tar} to ignore files that match the @var{pattern}.
+@end table
+
+@findex exclude
+The @option{--exclude=@var{pattern}} option prevents any file or member whose name
+matches the shell wildcard (@var{pattern}) from being operated on.
+For example, to create an archive with all the contents of the directory
+@file{src} except for files whose names end in @file{.o}, use the
+command @samp{tar -cf src.tar --exclude='*.o' src}.
+
+You may give multiple @option{--exclude} options.
+
+@table @option
+@opindex exclude-from
+@item --exclude-from=@var{file}
+@itemx -X @var{file}
+Causes @command{tar} to ignore files that match the patterns listed in
+@var{file}.
+@end table
+
+@findex exclude-from
+Use the @option{--exclude-from} option to read a
+list of patterns, one per line, from @var{file}; @command{tar} will
+ignore files matching those patterns. Thus if @command{tar} is
+called as @w{@samp{tar -c -X foo .}} and the file @file{foo} contains a
+single line @file{*.o}, no files whose names end in @file{.o} will be
+added to the archive.
+
+@FIXME{do the exclude options files need to have stuff separated by
+newlines the same as the files-from option does?}
+
+@table @option
+@opindex exclude-caches
+@item --exclude-caches
+Causes @command{tar} to ignore directories containing a cache directory tag.
+@end table
+
+@findex exclude-caches
+When creating an archive, the @option{--exclude-caches} option causes
+@command{tar} to exclude all directories that contain a @dfn{cache
+directory tag}. A cache directory tag is a short file with the
+well-known name @file{CACHEDIR.TAG} and having a standard header
+specified in @url{http://www.brynosaurus.com/cachedir/spec.html}.
+Various applications write cache directory tags into directories they
+use to hold regenerable, non-precious data, so that such data can be
+more easily excluded from backups.
+
+@menu
+* controlling pattern-matching with exclude::
+* problems with exclude::
+@end menu
+
+@node controlling pattern-matching with exclude
+@unnumberedsubsec Controlling Pattern-Matching with the @code{exclude} Options
+
+Normally, a pattern matches a name if an initial subsequence of the
+name's components matches the pattern, where @samp{*}, @samp{?}, and
+@samp{[...]} are the usual shell wildcards, @samp{\} escapes wildcards,
+and wildcards can match @samp{/}.
+
+Other than optionally stripping leading @samp{/} from names
+(@pxref{absolute}), patterns and names are used as-is. For
+example, trailing @samp{/} is not trimmed from a user-specified name
+before deciding whether to exclude it.
+
+However, this matching procedure can be altered by the options listed
+below. These options accumulate. For example:
+
+@smallexample
+--ignore-case --exclude='makefile' --no-ignore-case ---exclude='readme'
+@end smallexample
+
+ignores case when excluding @samp{makefile}, but not when excluding
+@samp{readme}.
+
+@table @option
+@opindex anchored
+@opindex no-anchored
+@item --anchored
+@itemx --no-anchored
+If anchored, a pattern must match an initial subsequence
+of the name's components. Otherwise, the pattern can match any
+subsequence. Default is @option{--no-anchored}.
+
+@opindex ignore-case
+@opindex no-ignore-case
+@item --ignore-case
+@itemx --no-ignore-case
+When ignoring case, upper-case patterns match lower-case names and vice versa.
+When not ignoring case (the default), matching is case-sensitive.
+
+@opindex wildcards
+@opindex no-wildcards
+@item --wildcards
+@itemx --no-wildcards
+When using wildcards (the default), @samp{*}, @samp{?}, and @samp{[...]}
+are the usual shell wildcards, and @samp{\} escapes wildcards.
+Otherwise, none of these characters are special, and patterns must match
+names literally.
+
+@opindex wildcards-match-slash
+@opindex no-wildcards-match-slash
+@item --wildcards-match-slash
+@itemx --no-wildcards-match-slash
+When wildcards match slash (the default), a wildcard like @samp{*} in
+the pattern can match a @samp{/} in the name. Otherwise, @samp{/} is
+matched only by @samp{/}.
-@table @samp
-@item +verbose
-@itemx -v
-Prints the names of files or archive members as they are being
-operated on. Can be used in conjunction with any operation. When
-used with @samp{+list}, generates an @samp{ls -l} type listing.
@end table
-To find out where in an archive a message was triggered, use
-@samp{+record-number}. @samp{+record-number} causes @code{tar} to
-print, along with every message it produces, the record number within
-the archive where the message was triggered.
+The @option{--recursion} and @option{--no-recursion} options
+(@pxref{recurse}) also affect how exclude patterns are interpreted. If
+recursion is in effect, a pattern excludes a name if it matches any of
+the name's parent directories.
-This option is especially useful when reading damaged archives, since
-it helps pinpoint the damaged sections. It can also be used with
-@samp{tar +list} when listing a file-system backup tape, allowing you
-to choose among several backup tapes when retrieving a file later, in
-favor of the tape where the file appears earliest (closest to the
-front of the tape).
-@c <<< xref when the node name is set and the backup section written
+@node problems with exclude
+@unnumberedsubsec Problems with Using the @code{exclude} Options
-@table @samp
-@item +record-number
-@itemx -R
-Prints the record number whenever a message is generated by
-@code{tar}. Use in conjunction with any operation.
-@end table
+@opindex exclude, potential problems with
+Some users find @samp{exclude} options confusing. Here are some common
+pitfalls:
-@c rewrite below
-To print the version number of the @code{tar} program, use @samp{tar
-+version}. @code{tar} prints the version number to the standard
-error. For example:
+@itemize @bullet
+@item
+The main operating mode of @command{tar} does not act on a path name
+explicitly listed on the command line if one of its file name
+components is excluded. In the example above, if
+you create an archive and exclude files that end with @samp{*.o}, but
+explicitly name the file @samp{dir.o/foo} after all the options have been
+listed, @samp{dir.o/foo} will be excluded from the archive.
+
+@item
+You can sometimes confuse the meanings of @option{--exclude} and
+@option{--exclude-from}. Be careful: use @option{--exclude} when files
+to be excluded are given as a pattern on the command line. Use
+@option{--exclude-from} to introduce the name of a file which contains
+a list of patterns, one per line; each of these patterns can exclude
+zero, one, or many files.
-@example
-tar +version
-@end example
+@item
+When you use @option{--exclude=@var{pattern}}, be sure to quote the @var{pattern}
+parameter, so @GNUTAR{} sees wildcard characters
+like @samp{*}. If you do not do this, the shell might expand the
+@samp{*} itself using files at hand, so @command{tar} might receive a
+list of files instead of one pattern, or none at all, making the
+command somewhat illegal. This might not correspond to what you want.
+
+For example, write:
+
+@smallexample
+$ @kbd{tar -c -f @var{archive.tar} --exclude '*.o' @var{directory}}
+@end smallexample
@noindent
-might return:
+rather than:
-@example
-GNU tar version 1.09
-@end example
-@c used to be an option. has been fixed.
+@smallexample
+$ @kbd{tar -c -f @var{archive.tar} --exclude *.o @var{directory}}
+@end smallexample
-@node Interactive Operation, , Additional Information, User Interaction
-@section Asking for Confirmation During Operations
-@cindex Interactive operation
+@item
+You must use use shell syntax, or globbing, rather than @code{regexp}
+syntax, when using exclude options in @command{tar}. If you try to use
+@code{regexp} syntax to describe files to be excluded, your command
+might fail.
-Typically, @code{tar} carries out a command without stopping for
-further instructions. In some situations however, you
-may want to exclude some files and archive members from the operation
-(for instance if disk or storage space is tight). You can do this by
-excluding certain files automatically (@pxref{File Exclusion}), or by
-performing an operation interactively, using the @samp{+interactive}
-operation.
-
-When the @samp{+interactive} option is specified, @code{tar} asks for
-confirmation before reading, writing, or deleting each file it
-encounters while carrying out an operation. To confirm the action you
-must type a line of input beginning with @samp{y}. If your input line
-begins with anything other than @samp{y}, @code{tar} skips that file.
-
-Commands which might be useful to perform interactively include
-appending files to an archive, extracting files from an archive,
-deleting a file from an archive, and deleting a file from disk during
-an incremental restore.
-
-If @code{tar} is reading the archive from the standard input,
-@code{tar} opens the file @file{/dev/tty} to support the interactive
-communications.
-<<< this aborts if you won't OK the working directory. this is a bug. -ringo
+@item
+In earlier versions of @command{tar}, what is now the
+@option{--exclude-from} option was called @option{--exclude} instead.
+Now, @option{--exclude} applies to patterns listed on the command
+line and @option{--exclude-from} applies to patterns listed in a
+file.
-@table @samp
-@item +interactive
-@itemx +confirmation
-@itemx -w
-Asks for confirmation before reading, writing or deleting an archive
-member (when listing, comparing or writing an archive or deleting
-archive members), or before writing or deleting a file (when
-extracting an archive).
+@end itemize
+
+@node Wildcards
+@section Wildcards Patterns and Matching
+
+@dfn{Globbing} is the operation by which @dfn{wildcard} characters,
+@samp{*} or @samp{?} for example, are replaced and expanded into all
+existing files matching the given pattern. However, @command{tar} often
+uses wildcard patterns for matching (or globbing) archive members instead
+of actual files in the file system. Wildcard patterns are also used for
+verifying volume labels of @command{tar} archives. This section has the
+purpose of explaining wildcard syntax for @command{tar}.
+
+@FIXME{the next few paragraphs need work.}
+
+A @var{pattern} should be written according to shell syntax, using wildcard
+characters to effect globbing. Most characters in the pattern stand
+for themselves in the matched string, and case is significant: @samp{a}
+will match only @samp{a}, and not @samp{A}. The character @samp{?} in the
+pattern matches any single character in the matched string. The character
+@samp{*} in the pattern matches zero, one, or more single characters in
+the matched string. The character @samp{\} says to take the following
+character of the pattern @emph{literally}; it is useful when one needs to
+match the @samp{?}, @samp{*}, @samp{[} or @samp{\} characters, themselves.
+
+The character @samp{[}, up to the matching @samp{]}, introduces a character
+class. A @dfn{character class} is a list of acceptable characters
+for the next single character of the matched string. For example,
+@samp{[abcde]} would match any of the first five letters of the alphabet.
+Note that within a character class, all of the ``special characters''
+listed above other than @samp{\} lose their special meaning; for example,
+@samp{[-\\[*?]]} would match any of the characters, @samp{-}, @samp{\},
+@samp{[}, @samp{*}, @samp{?}, or @samp{]}. (Due to parsing constraints,
+the characters @samp{-} and @samp{]} must either come @emph{first} or
+@emph{last} in a character class.)
+
+@cindex Excluding characters from a character class
+@cindex Character class, excluding characters from
+If the first character of the class after the opening @samp{[}
+is @samp{!} or @samp{^}, then the meaning of the class is reversed.
+Rather than listing character to match, it lists those characters which
+are @emph{forbidden} as the next single character of the matched string.
+
+Other characters of the class stand for themselves. The special
+construction @samp{[@var{a}-@var{e}]}, using an hyphen between two
+letters, is meant to represent all characters between @var{a} and
+@var{e}, inclusive.
+
+@FIXME{need to add a sentence or so here to make this clear for those
+who don't have dan around.}
+
+Periods (@samp{.}) or forward slashes (@samp{/}) are not considered
+special for wildcard matches. However, if a pattern completely matches
+a directory prefix of a matched string, then it matches the full matched
+string: excluding a directory also excludes all the files beneath it.
+
+@node after
+@section Operating Only on New Files
+@UNREVISED
+
+@cindex Excluding file by age
+@cindex Data Modification time, excluding files by
+@cindex Modification time, excluding files by
+@cindex Age, excluding files by
+The @option{--after-date=@var{date}} (@option{--newer=@var{date}},
+@option{-N @var{date}}) option causes @command{tar} to only work on
+files whose data modification or status change times are newer than
+the @var{date} given. If @var{date} starts with @samp{/} or @samp{.},
+it is taken to be a file name; the data modification time of that file
+is used as the date. If you use this option when creating or appending
+to an archive, the archive will only include new files. If you use
+@option{--after-date} when extracting an archive, @command{tar} will
+only extract files newer than the @var{date} you specify.
+
+If you only want @command{tar} to make the date comparison based on
+modification of the file's data (rather than status
+changes), then use the @option{--newer-mtime=@var{date}} option.
+
+You may use these options with any operation. Note that these options
+differ from the @option{--update} (@option{-u}) operation in that they
+allow you to specify a particular date against which @command{tar} can
+compare when deciding whether or not to archive the files.
+
+@table @option
+@opindex after-date
+@opindex newer
+@item --after-date=@var{date}
+@itemx --newer=@var{date}
+@itemx -N @var{date}
+Only store files newer than @var{date}.
+
+Acts on files only if their data modification or status change times are
+later than @var{date}. Use in conjunction with any operation.
+
+If @var{date} starts with @samp{/} or @samp{.}, it is taken to be a file
+name; the data modification time of that file is used as the date.
+
+@opindex newer-mtime
+@item --newer-mtime=@var{date}
+Acts like @option{--after-date}, but only looks at data modification times.
@end table
-@node Backups and Restoration, Media, User Interaction, Top
-@chapter Performing Backups and Restoring Files
+These options limit @command{tar} to operate only on files which have
+been modified after the date specified. A file's status is considered to have
+changed if its contents have been modified, or if its owner,
+permissions, and so forth, have been changed. (For more information on
+how to specify a date, see @ref{Date input formats}; remember that the
+entire date argument must be quoted if it contains any spaces.)
-To @dfn{back up} a file system means to create archives that contain
-all the files in that file system. Those archives can then be used to
-restore any or all of those files (for instance if a disk crashes or a
-file is accidently deleted). File system @dfn{backups} are also
-called @dfn{dumps}.
+Gurus would say that @option{--after-date} tests both the data
+modification time (@code{mtime}, the time the contents of the file
+were last modified) and the status change time (@code{ctime}, the time
+the file's status was last changed: owner, permissions, etc.@:)
+fields, while @option{--newer-mtime} tests only the @code{mtime}
+field.
-@menu
-* Backup Levels:: Levels of backups
-* Backup Scripts:: Using scripts to perform backups
- and restoration
-* incremental and listed-incremental:: The +incremental
- and +listed-incremental Options
-* Problems:: Some common problems and their solutions
-@end menu
+To be precise, @option{--after-date} checks @emph{both} @code{mtime} and
+@code{ctime} and processes the file if either one is more recent than
+@var{date}, while @option{--newer-mtime} only checks @code{mtime} and
+disregards @code{ctime}. Neither does it use @code{atime} (the last time the
+contents of the file were looked at).
-@node Backup Levels, Backup Scripts, Backups and Restoration, Backups and Restoration
-@section Levels of Backups
+Date specifiers can have embedded spaces. Because of this, you may need
+to quote date arguments to keep the shell from parsing them as separate
+arguments.
-An archive containing all the files in the file system is called a
-@dfn{full backup} or @dfn{full dump}. You could insure your data by
-creating a full dump every day. This strategy, however, would waste a
-substantial amount of archive media and user time, as unchanged files
-are daily re-archived.
+@FIXME{Need example of --newer-mtime with quoted argument.}
-It is more efficient to do a full dump only occasionally. To back up
-files between full dumps, you can a incremental dump. A @dfn{level
-one} dump archives all the files that have changed since the last full
-dump.
+@quotation
+@strong{Please Note:} @option{--after-date} and @option{--newer-mtime}
+should not be used for incremental backups. Some files (such as those
+in renamed directories) are not selected properly by these options.
+@xref{Incremental Dumps}.
+@end quotation
-A typical dump strategy would be to perform a full dump once a week,
-and a level one dump once a day. This means some versions of files
-will in fact be archived more than once, but this dump strategy makes
-it possible to restore a file system to within one day of accuracy by
-only extracting two archives---the last weekly (full) dump and the
-last daily (level one) dump. The only information lost would be in
-files changed or created since the last daily backup. (Doing dumps
-more than once a day is usually not worth the trouble).
+@noindent
+@FIXME{which tells -- need to fill this in!}
+
+@node recurse
+@section Descending into Directories
+@UNREVISED
+@cindex Avoiding recursion in directories
+@cindex Descending directories, avoiding
+@cindex Directories, avoiding recursion
+@cindex Recursion in directories, avoiding
+
+@FIXME{arrggh! this is still somewhat confusing to me. :-< }
+
+@FIXME{show dan bob's comments, from 2-10-97}
+
+Usually, @command{tar} will recursively explore all directories (either
+those given on the command line or through the @option{--files-from}
+option) for the various files they contain. However, you may not always
+want @command{tar} to act this way.
+
+@opindex no-recursion
+The @option{--no-recursion} option inhibits @command{tar}'s recursive descent
+into specified directories. If you specify @option{--no-recursion}, you can
+use the @command{find} utility for hunting through levels of directories to
+construct a list of file names which you could then pass to @command{tar}.
+@command{find} allows you to be more selective when choosing which files to
+archive; see @ref{files} for more information on using @command{find} with
+@command{tar}, or look.
+
+@table @option
+@item --no-recursion
+Prevents @command{tar} from recursively descending directories.
+
+@opindex recursion
+@item --recursion
+Requires @command{tar} to recursively descend directories.
+This is the default.
+@end table
+
+When you use @option{--no-recursion}, @GNUTAR{} grabs
+directory entries themselves, but does not descend on them
+recursively. Many people use @command{find} for locating files they
+want to back up, and since @command{tar} @emph{usually} recursively
+descends on directories, they have to use the @samp{@w{! -d}} option
+to @command{find} @FIXME{needs more explanation or a cite to another
+info file}as they usually do not want all the files in a directory.
+They then use the @option{--files-from} option to archive the files
+located via @command{find}.
+
+The problem when restoring files archived in this manner is that the
+directories themselves are not in the archive; so the
+@option{--same-permissions} (@option{--preserve-permissions},
+@option{-p}) option does not affect them---while users might really
+like it to. Specifying @option{--no-recursion} is a way to tell
+@command{tar} to grab only the directory entries given to it, adding
+no new files on its own.
+
+The @option{--no-recursion} option also applies when extracting: it
+causes @command{tar} to extract only the matched directory entries, not
+the files under those directories.
+
+The @option{--no-recursion} option also affects how exclude patterns
+are interpreted (@pxref{controlling pattern-matching with exclude}).
+
+The @option{--no-recursion} and @option{--recursion} options apply to
+later options and operands, and can be overridden by later occurrences
+of @option{--no-recursion} and @option{--recursion}. For example:
+
+@smallexample
+$ @kbd{tar -cf jams.tar --no-recursion grape --recursion grape/concord}
+@end smallexample
-@node Backup Scripts, incremental and listed-incremental, Backup Levels, Backups and Restoration
-@section Using Scripts to Perform Backups and Restoration
+@noindent
+creates an archive with one entry for @file{grape}, and the recursive
+contents of @file{grape/concord}, but no entries under @file{grape}
+other than @file{grape/concord}.
+
+@node one
+@section Crossing File System Boundaries
+@cindex File system boundaries, not crossing
+@UNREVISED
+
+@command{tar} will normally automatically cross file system boundaries in
+order to archive files which are part of a directory tree. You can
+change this behavior by running @command{tar} and specifying
+@option{--one-file-system} (@option{-l}). This option only affects files that are
+archived because they are in a directory that is being archived;
+@command{tar} will still archive files explicitly named on the command line
+or through @option{--files-from}, regardless of where they reside.
+
+@table @option
+@opindex one-file-system
+@item --one-file-system
+@itemx -l
+Prevents @command{tar} from crossing file system boundaries when
+archiving. Use in conjunction with any write operation.
+@end table
-GNU @code{tar} comes with scripts you can use to do full and level-one
-dumps. Using scripts (shell programs) to perform backups and
-restoration is a convenient and reliable alternative to typing out
-file name lists and @code{tar} commands by hand.
+The @option{--one-file-system} option causes @command{tar} to modify its
+normal behavior in archiving the contents of directories. If a file in
+a directory is not on the same file system as the directory itself, then
+@command{tar} will not archive that file. If the file is a directory
+itself, @command{tar} will not archive anything beneath it; in other words,
+@command{tar} will not cross mount points.
+
+It is reported that using this option, the mount point is is archived,
+but nothing under it.
+
+This option is useful for making full or incremental archival backups of
+a file system. If this option is used in conjunction with
+@option{--verbose} (@option{-v}), files that are excluded are mentioned by name on the
+standard error.
-Before you use these scripts, you need to edit the file
-@file{backup-specs}, which specifies parameters used by the backup
-scripts and by the restore script. @xref{Script Syntax}.
-Once the backup parameters are set, you can perform backups or
-restoration by running the appropriate script.
-
-The name of the restore script is @code{restore}. The names of the
-level one and full backup scripts are, respectively, @code{level-1} and
-@code{level-0}. The @code{level-0} script also exists under the name
-@code{weekly}, and the @code{level-1} under the name
-@code{daily}---these additional names can be changed according to your
-backup schedule. @xref{Scripted Restoration}, for more information
-on running the restoration script. @xref{Scripted Backups}, for more
-information on running the backup scripts.
-
-@emph{Please Note:} The backup scripts and the restoration scripts are
-designed to be used together. While it is possible to restore files
-by hand from an archive which was created using a backup script, and
-to create an archive by hand which could then be extracted using the
-restore script, it is easier to use the scripts. @xref{incremental
-and listed-incremental}, before making such an attempt.
-
-@c shorten node names
@menu
-* Backup Parameters:: Setting parameters for backups and restoration
-* Scripted Backups:: Using the backup scripts
-* Scripted Restoration:: Using the restore script
+* directory:: Changing Directory
+* absolute:: Absolute File Names
@end menu
-@node Backup Parameters, Scripted Backups, Backup Scripts, Backup Scripts
-@subsection Setting Parameters for Backups and Restoration
+@node directory
+@subsection Changing the Working Directory
+@UNREVISED
-The file @file{backup-specs} specifies backup parameters for the
-backup and restoration scripts provided with @code{tar}. You must
-edit @file{backup-specs} to fit your system configuration and schedule
-before using these scripts.
+@FIXME{need to read over this node now for continuity; i've switched
+things around some.}
-@c <<< This about backup scripts needs to be written:
-@c <<<BS is a shell script .... thus ... @file{backup-specs} is in shell
-@c script syntax. @xref{Script Syntax}, for an explanation of this
-@c syntax.
+@cindex Changing directory mid-stream
+@cindex Directory, changing mid-stream
+@cindex Working directory, specifying
+To change the working directory in the middle of a list of file names,
+either on the command line or in a file specified using
+@option{--files-from} (@option{-T}), use @option{--directory} (@option{-C}).
+This will change the working directory to the specified directory
+after that point in the list.
+
+@table @option
+@opindex directory
+@item --directory=@var{directory}
+@itemx -C @var{directory}
+Changes the working directory in the middle of a command line.
+@end table
-@c whats a parameter .... looked at by the backup scripts ... which will
-@c be expecting to find ... now syntax ... value is linked to lame ...
-@c @file{backup-specs} specifies the following parameters:
+For example,
+@smallexample
+$ @kbd{tar -c -f jams.tar grape prune -C food cherry}
+@end smallexample
-@table @code
-@item ADMINISTRATOR
-The user name of the backup administrator.
+@noindent
+will place the files @file{grape} and @file{prune} from the current
+directory into the archive @file{jams.tar}, followed by the file
+@file{cherry} from the directory @file{food}. This option is especially
+useful when you have several widely separated files that you want to
+store in the same archive.
+
+Note that the file @file{cherry} is recorded in the archive under the
+precise name @file{cherry}, @emph{not} @file{food/cherry}. Thus, the
+archive will contain three files that all appear to have come from the
+same directory; if the archive is extracted with plain @samp{tar
+--extract}, all three files will be written in the current directory.
-@item BACKUP_HOUR
-The hour at which the backups are done. This can be a number from 0
-to 23, or the string @samp{now}.
+Contrast this with the command,
-@item TAPE_FILE
-The device @code{tar} writes the archive to. This device should be
-attached to the host on which the dump scripts are run.
-@c <<< examples for all ...
+@smallexample
+$ @kbd{tar -c -f jams.tar grape prune -C food red/cherry}
+@end smallexample
-@item TAPE_STATUS
-The command to use to obtain the status of the archive device,
-including error count. On some tape drives there may not be such a
-command; in that case, simply use `TAPE_STATUS=false'.
+@noindent
+which records the third file in the archive under the name
+@file{red/cherry} so that, if the archive is extracted using
+@samp{tar --extract}, the third file will be written in a subdirectory
+named @file{orange-colored}.
-@item BLOCKING
-The blocking factor @code{tar} will use when writing the dump archive.
-@xref{Blocking Factor}.
+You can use the @option{--directory} option to make the archive
+independent of the original name of the directory holding the files.
+The following command places the files @file{/etc/passwd},
+@file{/etc/hosts}, and @file{/lib/libc.a} into the archive
+@file{foo.tar}:
-@item BACKUP_DIRS
-A list of file systems to be dumped. You can include any directory
-name in the list---subdirectories on that file system will be
-included, regardless of how they may look to other networked machines.
-Subdirectories on other file systems will be ignored.
+@smallexample
+$ @kbd{tar -c -f foo.tar -C /etc passwd hosts -C /lib libc.a}
+@end smallexample
-The host name specifies which host to run @code{tar} on, and should
-normally be the host that actually contains the file system. However,
-the host machine must have GNU @code{tar} installed, and must be able
-to access the directory containing the backup scripts and their
-support files using the same file name that is used on the machine
-where the scripts are run (ie. what @code{pwd} will print when in that
-directory on that machine). If the host that contains the file system
-does not have this capability, you can specify another host as long as
-it can access the file system through NFS.
+@noindent
+However, the names of the archive members will be exactly what they were
+on the command line: @file{passwd}, @file{hosts}, and @file{libc.a}.
+They will not appear to be related by file name to the original
+directories where those files were located.
+
+Note that @option{--directory} options are interpreted consecutively. If
+@option{--directory} specifies a relative file name, it is interpreted
+relative to the then current directory, which might not be the same as
+the original current working directory of @command{tar}, due to a previous
+@option{--directory} option.
+
+When using @option{--files-from} (@pxref{files}), you can put various
+@command{tar} options (including @option{-C}) in the file list. Notice,
+however, that in this case the option and its argument may not be
+separated by whitespace. If you use short option, its argument must
+either follow the option letter immediately, without any intervening
+whitespace, or occupy the next line. Otherwise, if you use long
+option, separate its argument by an equal sign.
+
+For instance, the file list for the above example will be:
+
+@smallexample
+@group
+-C
+/etc
+passwd
+hosts
+-C
+/lib
+libc.a
+@end group
+@end smallexample
+
+@noindent
+To use it, you would invoke @command{tar} as follows:
+
+@smallexample
+$ @kbd{tar -c -f foo.tar --files-from list}
+@end smallexample
+
+Notice also that you can only use the short option variant in the file
+list, i.e., always use @option{-C}, not @option{--directory}.
+
+The interpretation of @option{--directory} is disabled by
+@option{--null} option.
+
+@node absolute
+@subsection Absolute File Names
+@UNREVISED
+
+@table @option
+@opindex absolute-names
+@item --absolute-names
+@itemx -P
+Do not strip leading slashes from file names, and permit file names
+containing a @file{..} file name component.
+@end table
+
+By default, @GNUTAR{} drops a leading @samp{/} on
+input or output, and complains about file names containing a @file{..}
+component. This option turns off this behavior.
+
+When @command{tar} extracts archive members from an archive, it strips any
+leading slashes (@samp{/}) from the member name. This causes absolute
+member names in the archive to be treated as relative file names. This
+allows you to have such members extracted wherever you want, instead of
+being restricted to extracting the member in the exact directory named
+in the archive. For example, if the archive member has the name
+@file{/etc/passwd}, @command{tar} will extract it as if the name were
+really @file{etc/passwd}.
+
+File names containing @file{..} can cause problems when extracting, so
+@command{tar} normally warns you about such files when creating an
+archive, and rejects attempts to extracts such files.
+
+Other @command{tar} programs do not do this. As a result, if you
+create an archive whose member names start with a slash, they will be
+difficult for other people with a non-@GNUTAR{}
+program to use. Therefore, @GNUTAR{} also strips
+leading slashes from member names when putting members into the
+archive. For example, if you ask @command{tar} to add the file
+@file{/bin/ls} to an archive, it will do so, but the member name will
+be @file{bin/ls}.@footnote{A side effect of this is that when
+@option{--create} is used with @option{--verbose} the resulting output
+is not, generally speaking, the same as the one you'd get running
+@kbd{tar --list} command. This may be important if you use some
+scripts for comparing both outputs. @xref{listing member and file names},
+for the information on how to handle this case.}
+
+If you use the @option{--absolute-names} (@option{-P}) option,
+@command{tar} will do none of these transformations.
+
+To archive or extract files relative to the root directory, specify
+the @option{--absolute-names} (@option{-P}) option.
+
+Normally, @command{tar} acts on files relative to the working
+directory---ignoring superior directory names when archiving, and
+ignoring leading slashes when extracting.
+
+When you specify @option{--absolute-names} (@option{-P}),
+@command{tar} stores file names including all superior directory
+names, and preserves leading slashes. If you only invoked
+@command{tar} from the root directory you would never need the
+@option{--absolute-names} option, but using this option
+may be more convenient than switching to root.
+
+@FIXME{Should be an example in the tutorial/wizardry section using this
+to transfer files between systems.}
+
+@FIXME{Is write access an issue?}
+
+@table @option
+@item --absolute-names
+Preserves full file names (including superior directory names) when
+archiving files. Preserves leading slash when extracting files.
+
+@end table
+
+@FIXME{this is still horrible; need to talk with dan on monday.}
+
+@command{tar} prints out a message about removing the @samp{/} from
+file names. This message appears once per @GNUTAR{}
+invocation. It represents something which ought to be told; ignoring
+what it means can cause very serious surprises, later.
+
+Some people, nevertheless, do not want to see this message. Wanting to
+play really dangerously, one may of course redirect @command{tar} standard
+error to the sink. For example, under @command{sh}:
+
+@smallexample
+$ @kbd{tar -c -f archive.tar /home 2> /dev/null}
+@end smallexample
+
+@noindent
+Another solution, both nicer and simpler, would be to change to
+the @file{/} directory first, and then avoid absolute notation.
+For example:
+
+@smallexample
+$ @kbd{(cd / && tar -c -f archive.tar home)}
+$ @kbd{tar -c -f archive.tar -C / home}
+@end smallexample
+
+@include getdate.texi
+
+@node Formats
+@chapter Controlling the Archive Format
+
+@cindex Tar archive formats
+Due to historical reasons, there are several formats of tar archives.
+All of them are based on the same principles, but have some subtle
+differences that often make them incompatible with each other.
+
+GNU tar is able to create and handle archives in a variety of formats.
+The most frequently used formats are (in alphabetical order):
+
+@table @asis
+@item gnu
+Format used by @GNUTAR{} versions up to 1.13.25. This format derived
+from an early @acronym{POSIX} standard, adding some improvements such as
+sparse file handling and incremental archives. Unfortunately these
+features were implemented in a way incompatible with other archive
+formats.
+
+Archives in @samp{gnu} format are able to hold pathnames of unlimited
+length.
+
+@item oldgnu
+Format used by @GNUTAR{} of versions prior to 1.12.
+
+@item v7
+Archive format, compatible with the V7 implementation of tar. This
+format imposes a number of limitations. The most important of them
+are:
+
+@enumerate
+@item The maximum length of a file name is limited to 99 characters.
+@item The maximum length of a symbolic link is limited to 99 characters.
+@item It is impossible to store special files (block and character
+devices, fifos etc.)
+@item Maximum value of user or group ID is limited to 2097151 (7777777
+octal)
+@item V7 archives do not contain symbolic ownership information (user
+and group name of the file owner).
+@end enumerate
+
+This format has traditionally been used by Automake when producing
+Makefiles. This practice will change in the future, in the meantime,
+however this means that projects containing filenames more than 99
+characters long will not be able to use @GNUTAR{} @value{VERSION} and
+Automake prior to 1.9.
+
+@item ustar
+Archive format defined by @acronym{POSIX.1-1988} specification. It stores
+symbolic ownership information. It is also able to store
+special files. However, it imposes several restrictions as well:
+
+@enumerate
+@item The maximum length of a file name is limited to 256 characters,
+provided that the filename can be split at directory separator in
+two parts, first of them being at most 155 bytes long. So, in most
+cases the maximum file name length will be shorter than 256
+characters.
+@item The maximum length of a symbolic link name is limited to
+100 characters.
+@item Maximum size of a file the archive is able to accomodate
+is 8GB
+@item Maximum value of UID/GID is 2097151.
+@item Maximum number of bits in device major and minor numbers is 21.
+@end enumerate
+
+@item star
+Format used by J@"org Schilling @command{star}
+implementation. @GNUTAR{} is able to read @samp{star} archives but
+currently does not produce them.
+
+@item posix
+Archive format defined by @acronym{POSIX.1-2001} specification. This is the
+most flexible and feature-rich format. It does not impose any
+restrictions on file sizes or filename lengths. This format is quite
+recent, so not all tar implementations are able to handle it properly.
+However, this format is designed in such a way that any tar
+implementation able to read @samp{ustar} archives will be able to read
+most @samp{posix} archives as well, with the only exception that any
+additional information (such as long file names etc.) will in such
+case be extracted as plain text files along with the files it refers to.
+
+This archive format will be the default format for future versions
+of @GNUTAR{}.
-@item BACKUP_FILES
-A list of individual files to be dumped. These should be accessible
-from the machine on which the backup script is run.
-@c <<<same file name, be specific. through nfs ...
@end table
+The following table summarizes the limitations of each of these
+formats:
+
+@multitable @columnfractions .10 .20 .20 .20 .20
+@headitem Format @tab UID @tab File Size @tab Path Name @tab Devn
+@item gnu @tab 1.8e19 @tab Unlimited @tab Unlimited @tab 63
+@item oldgnu @tab 1.8e19 @tab Unlimited @tab Unlimited @tab 63
+@item v7 @tab 2097151 @tab 8GB @tab 99 @tab n/a
+@item ustar @tab 2097151 @tab 8GB @tab 256 @tab 21
+@item posix @tab Unlimited @tab Unlimited @tab Unlimited @tab Unlimited
+@end multitable
+
+The default format for @GNUTAR{} is defined at compilation
+time. You may check it by running @command{tar --help}, and examining
+the last lines of its output. Usually, @GNUTAR{} is configured
+to create archives in @samp{gnu} format, however, future version will
+switch to @samp{posix}.
+
@menu
-* backup-specs example:: An Example Text of @file{Backup-specs}
-* Script Syntax:: Syntax for @file{Backup-specs}
+* Portability:: Making @command{tar} Archives More Portable
+* Compression:: Using Less Space through Compression
+* Attributes:: Handling File Attributes
+* Standard:: The Standard Format
+* Extensions:: @acronym{GNU} Extensions to the Archive Format
+* cpio:: Comparison of @command{tar} and @command{cpio}
@end menu
-@node backup-specs example, Script Syntax, Backup Parameters, Backup Parameters
-@subsubsection An Example Text of @file{Backup-specs}
+@node Portability
+@section Making @command{tar} Archives More Portable
-The following is the text of @file{backup-specs} as it appears at FSF:
+Creating a @command{tar} archive on a particular system that is meant to be
+useful later on many other machines and with other versions of @command{tar}
+is more challenging than you might think. @command{tar} archive formats
+have been evolving since the first versions of Unix. Many such formats
+are around, and are not always compatible with each other. This section
+discusses a few problems, and gives some advice about making @command{tar}
+archives more portable.
-@example
-# site-specific parameters for file system backup.
+One golden rule is simplicity. For example, limit your @command{tar}
+archives to contain only regular files and directories, avoiding
+other kind of special files. Do not attempt to save sparse files or
+contiguous files as such. Let's discuss a few more problems, in turn.
-ADMINISTRATOR=friedman
-BACKUP_HOUR=1
-TAPE_FILE=/dev/nrsmt0
-TAPE_STATUS="mts -t $TAPE_FILE"
-BLOCKING=124
-BACKUP_DIRS="
- albert:/fs/fsf
- apple-gunkies:/gd
- albert:/fs/gd2
- albert:/fs/gp
- geech:/usr/jla
- churchy:/usr/roland
- albert:/
- albert:/usr
- apple-gunkies:/
- apple-gunkies:/usr
- gnu:/hack
- gnu:/u
- apple-gunkies:/com/mailer/gnu
- apple-gunkies:/com/archive/gnu"
+@FIXME{Discuss GNU extensions (incremental backups, multi-volume
+archives and archive labels) in GNU and PAX formats.}
-BACKUP_FILES="/com/mailer/aliases /com/mailer/league*[a-z]"
+@menu
+* Portable Names:: Portable Names
+* dereference:: Symbolic Links
+* old:: Old V7 Archives
+* ustar:: Ustar Archives
+* gnu:: GNU and old GNU format archives.
+* posix:: @acronym{POSIX} archives
+* Checksumming:: Checksumming Problems
+* Large or Negative Values:: Large files, negative time stamps, etc.
+@end menu
+
+@node Portable Names
+@subsection Portable Names
+
+Use portable file and member names. A name is portable if it contains
+only ASCII letters and digits, @samp{/}, @samp{.}, @samp{_}, and
+@samp{-}; it cannot be empty, start with @samp{-} or @samp{//}, or
+contain @samp{/-}. Avoid deep directory nesting. For portability to
+old Unix hosts, limit your file name components to 14 characters or
+less.
+
+If you intend to have your @command{tar} archives to be read under
+MSDOS, you should not rely on case distinction for file names, and you
+might use the @acronym{GNU} @command{doschk} program for helping you
+further diagnosing illegal MSDOS names, which are even more limited
+than System V's.
+
+@node dereference
+@subsection Symbolic Links
+@cindex File names, using symbolic links
+@cindex Symbolic link as file name
-@end example
+@opindex dereference
+Normally, when @command{tar} archives a symbolic link, it writes a
+block to the archive naming the target of the link. In that way, the
+@command{tar} archive is a faithful record of the file system contents.
+@option{--dereference} (@option{-h}) is used with @option{--create} (@option{-c}), and causes
+@command{tar} to archive the files symbolic links point to, instead of
+the links themselves. When this option is used, when @command{tar}
+encounters a symbolic link, it will archive the linked-to file,
+instead of simply recording the presence of a symbolic link.
-@node Script Syntax, , backup-specs example, Backup Parameters
-@subsubsection Syntax for @file{Backup-specs}
+The name under which the file is stored in the file system is not
+recorded in the archive. To record both the symbolic link name and
+the file name in the system, archive the file under both names. If
+all links were recorded automatically by @command{tar}, an extracted file
+might be linked to a file name that no longer exists in the file
+system.
-@file{backup-specs} is in shell script syntax. The following
-conventions should be considered when editing the script:
-@c <<< "conventions?"
+If a linked-to file is encountered again by @command{tar} while creating
+the same archive, an entire second copy of it will be stored. (This
+@emph{might} be considered a bug.)
-A quoted string is considered to be contiguous, even if it is on more
-than one line. Therefore, you cannot include commented-out lines
-within a multi-line quoted string. BACKUP_FILES and BACKUP_DIRS are
-the two most likely parameters to be multi-line.
+So, for portable archives, do not archive symbolic links as such,
+and use @option{--dereference} (@option{-h}): many systems do not support
+symbolic links, and moreover, your distribution might be unusable if
+it contains unresolved symbolic links.
-A quoted string typically cannot contain wildcards. In
-@file{backup-specs}, however, the parameters BACKUP_DIRS and
-BACKUP_FILES can contain wildcards.
+@node old
+@subsection Old V7 Archives
+@cindex Format, old style
+@cindex Old style format
+@cindex Old style archives
+@cindex v7 archive format
+
+Certain old versions of @command{tar} cannot handle additional
+information recorded by newer @command{tar} programs. To create an
+archive in V7 format (not ANSI), which can be read by these old
+versions, specify the @option{--format=v7} option in
+conjunction with the @option{--create} (@option{-c}) (@command{tar} also
+accepts @option{--portability} or @samp{op-old-archive} for this
+option). When you specify it,
+@command{tar} leaves out information about directories, pipes, fifos,
+contiguous files, and device files, and specifies file ownership by
+group and user IDs instead of group and user names.
+
+When updating an archive, do not use @option{--format=v7}
+unless the archive was created using this option.
+
+In most cases, a @emph{new} format archive can be read by an @emph{old}
+@command{tar} program without serious trouble, so this option should
+seldom be needed. On the other hand, most modern @command{tar}s are
+able to read old format archives, so it might be safer for you to
+always use @option{--format=v7} for your distributions.
+
+@node ustar
+@subsection Ustar Archive Format
+
+@cindex ustar archive format
+Archive format defined by @acronym{POSIX}.1-1988 specification is called
+@code{ustar}. Although it is more flexible than the V7 format, it
+still has many restrictions (@xref{Formats,ustar}, for the detailed
+description of @code{ustar} format). Along with V7 format,
+@code{ustar} format is a good choice for archives intended to be read
+with other implementations of @command{tar}.
+
+To create archive in @code{ustar} format, use @option{--format=ustar}
+option in conjunction with the @option{--create} (@option{-c}).
+
+@node gnu
+@subsection @acronym{GNU} and old @GNUTAR{} format
+
+@cindex GNU archive format
+@cindex Old GNU archive format
+@GNUTAR{} was based on an early draft of the
+@acronym{POSIX} 1003.1 @code{ustar} standard. @acronym{GNU} extensions to
+@command{tar}, such as the support for file names longer than 100
+characters, use portions of the @command{tar} header record which were
+specified in that @acronym{POSIX} draft as unused. Subsequent changes in
+@acronym{POSIX} have allocated the same parts of the header record for
+other purposes. As a result, @GNUTAR{} format is
+incompatible with the current @acronym{POSIX} specification, and with
+@command{tar} programs that follow it.
+
+In the majority of cases, @command{tar} will be configured to create
+this format by default. This will change in the future releases, since
+we plan to make @samp{posix} format the default.
+
+To force creation a @GNUTAR{} archive, use option
+@option{--format=gnu}.
+
+@node posix
+@subsection @GNUTAR{} and @acronym{POSIX} @command{tar}
+
+@cindex POSIX archive format
+@cindex PAX archive format
+The version @value{VERSION} of @GNUTAR{} is able
+to read and create archives conforming to @acronym{POSIX.1-2001} standard.
+
+A @acronym{POSIX} conformant archive will be created if @command{tar}
+was given @option{--format=posix} option.
+
+@node Checksumming
+@subsection Checksumming Problems
+
+SunOS and HP-UX @command{tar} fail to accept archives created using
+@GNUTAR{} and containing non-ASCII file names, that
+is, file names having characters with the eight bit set, because they
+use signed checksums, while @GNUTAR{} uses unsigned
+checksums while creating archives, as per @acronym{POSIX} standards. On
+reading, @GNUTAR{} computes both checksums and
+accept any. It is somewhat worrying that a lot of people may go
+around doing backup of their files using faulty (or at least
+non-standard) software, not learning about it until it's time to
+restore their missing files with an incompatible file extractor, or
+vice versa.
+
+@GNUTAR{} compute checksums both ways, and accept
+any on read, so @acronym{GNU} tar can read Sun tapes even with their
+wrong checksums. @GNUTAR{} produces the standard
+checksum, however, raising incompatibilities with Sun. That is to
+say, @GNUTAR{} has not been modified to
+@emph{produce} incorrect archives to be read by buggy @command{tar}'s.
+I've been told that more recent Sun @command{tar} now read standard
+archives, so maybe Sun did a similar patch, after all?
+
+The story seems to be that when Sun first imported @command{tar}
+sources on their system, they recompiled it without realizing that
+the checksums were computed differently, because of a change in
+the default signing of @code{char}'s in their compiler. So they
+started computing checksums wrongly. When they later realized their
+mistake, they merely decided to stay compatible with it, and with
+themselves afterwards. Presumably, but I do not really know, HP-UX
+has chosen that their @command{tar} archives to be compatible with Sun's.
+The current standards do not favor Sun @command{tar} format. In any
+case, it now falls on the shoulders of SunOS and HP-UX users to get
+a @command{tar} able to read the good archives they receive.
+
+@node Large or Negative Values
+@subsection Large or Negative Values
+@cindex large values
+@cindex future time stamps
+@cindex negative time stamps
+@UNREVISED{}
+
+The above sections suggest to use @samp{oldest possible} archive
+format if in doubt. However, sometimes it is not possible. If you
+attempt to archive a file whose metadata cannot be represented using
+required format, @GNUTAR{} will print error message and ignore such a
+file. You will than have to switch to a format that is able to
+handle such values. The format summary table (@pxref{Formats}) will
+help you to do so.
+
+In particular, when trying to archive files larger than 8GB or with
+timestamps not in the range 1970-01-01 00:00:00 through 2242-03-16
+12:56:31 @sc{utc}, you will have to chose between @acronym{GNU} and
+@acronym{POSIX} archive formats. When considering which format to
+choose, bear in mind that the @acronym{GNU} format uses
+two's-complement base-256 notation to store values that do not fit
+into standard @acronym{ustar} range. Such archives can generally be
+read only by a @GNUTAR{} implementation. Moreover, they sometimes
+cannot be correctly restored on another hosts even by @GNUTAR{}. For
+example, using two's complement representation for negative time
+stamps that assumes a signed 32-bit @code{time_t} generates archives
+that are not portable to hosts with differing @code{time_t}
+representations.
+
+On the other hand, @acronym{POSIX} archives, generally speaking, can
+be extracted by any tar implementation that understands older
+@acronym{ustar} format. The only exception are files larger than 8GB.
+
+@FIXME{Describe how @acronym{POSIX} archives are extracted by non
+POSIX-aware tars.}
+
+@node Compression
+@section Using Less Space through Compression
-@node Scripted Backups, Scripted Restoration, Backup Parameters, Backup Scripts
-@subsection Using the Backup Scripts
+@menu
+* gzip:: Creating and Reading Compressed Archives
+* sparse:: Archiving Sparse Files
+@end menu
-The syntax for running a backup script is:
+@node gzip
+@subsection Creating and Reading Compressed Archives
+@cindex Compressed archives
+@cindex Storing archives in compressed format
-@example
-@file{script-name} [@var{time-to-be-run}]
-@end example
+@GNUTAR{} is able to create and read compressed archives. It supports
+@command{gzip} and @command{bzip2} compression programs. For backward
+compatibilty, it also supports @command{compress} command, although
+we strongly recommend against using it, since there is a patent
+covering the algorithm it uses and you could be sued for patent
+infringement merely by running @command{compress}! Besides, it is less
+effective than @command{gzip} and @command{bzip2}.
+
+Creating a compressed archive is simple: you just specify a
+@dfn{compression option} along with the usual archive creation
+commands. The compression option is @option{-z} (@option{--gzip}) to
+create a @command{gzip} compressed archive, @option{-j}
+(@option{--bzip2}) to create a @command{bzip2} compressed archive, and
+@option{-Z} (@option{--compress}) to use @command{compress} program.
+For example:
-where @var{time-to-be-run} can be a specific system time, or can be
-@kbd{now}. If you do not specify a time, the script runs at the time
-specified in @file{backup-specs} (@pxref{Script Syntax}).
+@smallexample
+$ @kbd{tar cfz archive.tar.gz .}
+@end smallexample
+
+Reading compressed archive is even simpler: you don't need to specify
+any additional options as @GNUTAR{} recognizes its format
+automatically. Thus, the following commands will list and extract the
+archive created in previous example:
+
+@smallexample
+# List the compressed archive
+$ @kbd{tar tf archive.tar.gz}
+# Extract the compressed archive
+$ @kbd{tar xf archive.tar.gz}
+@end smallexample
+
+The only case when you have to specify a decompression option while
+reading the archive is when reading from a pipe or from a tape drive
+that does not support random access. However, in this case @GNUTAR{}
+will indicate which option you should use. For example:
+
+@smallexample
+$ @kbd{cat archive.tar.gz | tar tf -}
+tar: Archive is compressed. Use -z option
+tar: Error is not recoverable: exiting now
+@end smallexample
+
+If you see such diagnostics, just add the suggested option to the
+invocation of @GNUTAR{}:
+
+@smallexample
+$ @kbd{cat archive.tar.gz | tar tfz -}
+@end smallexample
+
+Notice also, that there are several restrictions on operations on
+compressed archives. First of all, compressed archives cannot be
+modified, i.e., you cannot update (@option{--update} (@option{-u})) them or delete
+(@option{--delete}) members from them. Likewise, you cannot append
+another @command{tar} archive to a compressed archive using
+@option{--append} (@option{-r})). Secondly, multi-volume archives cannot be
+compressed.
+
+The following table summarizes compression options used by @GNUTAR{}.
+
+@table @option
+@opindex gzip
+@opindex ungzip
+@item -z
+@itemx --gzip
+@itemx --ungzip
+Filter the archive through @command{gzip}.
-You should start a script with a tape or disk mounted. Once you start
-a script, it prompts you for new tapes or disks as it needs them.
-Media volumes don't have to correspond to archive files---a
-multi-volume archive can be started in the middle of a tape that
-already contains the end of another multi-volume archive. The
-@code{restore} script prompts for media by its archive volume, so to
-avoid an error message you should keep track of which tape (or disk)
-contains which volume of the archive. @xref{Scripted Restoration}.
+You can use @option{--gzip} and @option{--gunzip} on physical devices
+(tape drives, etc.) and remote files as well as on normal files; data
+to or from such devices or remote files is reblocked by another copy
+of the @command{tar} program to enforce the specified (or default) record
+size. The default compression parameters are used; if you need to
+override them, set @env{GZIP} environment variable, e.g.:
-@c <<<have file names changed? -ringo
-The backup scripts write two files on the file system. The first is a
-record file in @file{/etc/tar-backup/}, which is used by the scripts
-to store and retrieve information about which files were dumped. This
-file is not meant to be read by humans, and should not be deleted by
-them. @xref{incremental and listed-incremental}, for a more
-detailed explanation of this file.
+@smallexample
+$ @kbd{GZIP=--best tar cfz archive.tar.gz subdir}
+@end smallexample
-The second file is a log file containing the names of the file systems
-and files dumped, what time the backup was made, and any error
-messages that were generated, as well as how much space was left in
-the media volume after the last volume of the archive was written.
-You should check this log file after every backup. The file name is
-@file{log-@var{mmm-ddd-yyyy}-level-1} or
-@file{log-@var{mmm-ddd-yyyy}-full}.
+@noindent
+Another way would be to avoid the @option{--gzip} (@option{--gunzip}, @option{--ungzip}, @option{-z}) option and run
+@command{gzip} explicitly:
+
+@smallexample
+$ @kbd{tar cf - subdir | gzip --best -c - > archive.tar.gz}
+@end smallexample
+
+@cindex corrupted archives
+About corrupted compressed archives: @command{gzip}'ed files have no
+redundancy, for maximum compression. The adaptive nature of the
+compression scheme means that the compression tables are implicitly
+spread all over the archive. If you lose a few blocks, the dynamic
+construction of the compression tables becomes unsynchronized, and there
+is little chance that you could recover later in the archive.
+
+There are pending suggestions for having a per-volume or per-file
+compression in @GNUTAR{}. This would allow for viewing the
+contents without decompression, and for resynchronizing decompression at
+every volume or file, in case of corrupted archives. Doing so, we might
+lose some compressibility. But this would have make recovering easier.
+So, there are pros and cons. We'll see!
+
+@opindex bzip2
+@item -j
+@itemx --bzip2
+Filter the archive through @code{bzip2}. Otherwise like @option{--gzip}.
+
+@opindex compress
+@opindex uncompress
+@item -Z
+@itemx --compress
+@itemx --uncompress
+Filter the archive through @command{compress}. Otherwise like @option{--gzip}.
+
+The @acronym{GNU} Project recommends you not use
+@command{compress}, because there is a patent covering the algorithm it
+uses. You could be sued for patent infringement merely by running
+@command{compress}.
+
+@opindex use-compress-program
+@item --use-compress-program=@var{prog}
+Use external compression program @var{prog}. Use this option if you
+have a compression program that @GNUTAR{} does not support. There
+are two requirements to which @var{prog} should comply:
+
+First, when called without options, it should read data from standard
+input, compress it and output it on standard output.
+
+Secondly, if called with @option{-d} argument, it should do exactly
+the opposite, i.e., read the compressed data from the standard input
+and produce uncompressed data on the standard output.
+@end table
-The script also prints the name of each system being dumped to the
-standard output.
-@c <<<the section on restore scripts is commented out.
-@c <<< a section on non-scripted testore mya be a good idea
-@ignore
-@node Scripted Restoration, , Scripted Backups, Backup Scripts
-@subsection Using the Restore Script
-@c subject to change as things develop
+@FIXME{I have one question, or maybe it's a suggestion if there isn't a way
+to do it now. I would like to use @option{--gzip}, but I'd also like
+the output to be fed through a program like @acronym{GNU}
+@command{ecc} (actually, right now that's @samp{exactly} what I'd like
+to use :-)), basically adding ECC protection on top of compression.
+It seems as if this should be quite easy to do, but I can't work out
+exactly how to go about it. Of course, I can pipe the standard output
+of @command{tar} through @command{ecc}, but then I lose (though I
+haven't started using it yet, I confess) the ability to have
+@command{tar} use @command{rmt} for it's I/O (I think).
+
+I think the most straightforward thing would be to let me specify a
+general set of filters outboard of compression (preferably ordered,
+so the order can be automatically reversed on input operations, and
+with the options they require specifiable), but beggars shouldn't be
+choosers and anything you decide on would be fine with me.
+
+By the way, I like @command{ecc} but if (as the comments say) it can't
+deal with loss of block sync, I'm tempted to throw some time at adding
+that capability. Supposing I were to actually do such a thing and
+get it (apparently) working, do you accept contributed changes to
+utilities like that? (Leigh Clayton @file{loc@@soliton.com}, May 1995).
+
+Isn't that exactly the role of the @option{--use-compress-prog=@var{program}} option?
+I never tried it myself, but I suspect you may want to write a
+@var{prog} script or program able to filter stdin to stdout to
+way you want. It should recognize the @option{-d} option, for when
+extraction is needed rather than creation.
+
+It has been reported that if one writes compressed data (through the
+@option{--gzip} or @option{--compress} options) to a DLT and tries to use
+the DLT compression mode, the data will actually get bigger and one will
+end up with less space on the tape.}
+
+@node sparse
+@subsection Archiving Sparse Files
+@cindex Sparse Files
+@UNREVISED
-To restore files that were archived using a scripted backup, use the
-@code{restore} script. The syntax for the script is:
+@table @option
+@opindex sparse
+@item -S
+@itemx --sparse
+Handle sparse files efficiently.
+@end table
+This option causes all files to be put in the archive to be tested for
+sparseness, and handled specially if they are. The @option{--sparse}
+(@option{-S}) option is useful when many @code{dbm} files, for example, are being
+backed up. Using this option dramatically decreases the amount of
+space needed to store such a file.
+
+In later versions, this option may be removed, and the testing and
+treatment of sparse files may be done automatically with any special
+@acronym{GNU} options. For now, it is an option needing to be specified on
+the command line with the creation or updating of an archive.
+
+Files in the file system occasionally have ``holes.'' A hole in a file
+is a section of the file's contents which was never written. The
+contents of a hole read as all zeros. On many operating systems,
+actual disk storage is not allocated for holes, but they are counted
+in the length of the file. If you archive such a file, @command{tar}
+could create an archive longer than the original. To have @command{tar}
+attempt to recognize the holes in a file, use @option{--sparse} (@option{-S}). When
+you use this option, then, for any file using less disk space than
+would be expected from its length, @command{tar} searches the file for
+consecutive stretches of zeros. It then records in the archive for
+the file where the consecutive stretches of zeros are, and only
+archives the ``real contents'' of the file. On extraction (using
+@option{--sparse} is not needed on extraction) any such
+files have holes created wherever the continuous stretches of zeros
+were found. Thus, if you use @option{--sparse}, @command{tar} archives
+won't take more space than the original.
+
+A file is sparse if it contains blocks of zeros whose existence is
+recorded, but that have no space allocated on disk. When you specify
+the @option{--sparse} option in conjunction with the @option{--create}
+(@option{-c}) operation, @command{tar} tests all files for sparseness
+while archiving. If @command{tar} finds a file to be sparse, it uses a
+sparse representation of the file in the archive. @xref{create}, for
+more information about creating archives.
-where ##### are the file systems to restore from, and
-##### is a regular expression which specifies which files to
-restore. If you specify +all, the script restores all the files
-in the file system.
+@option{--sparse} is useful when archiving files, such as dbm files,
+likely to contain many nulls. This option dramatically
+decreases the amount of space needed to store such an archive.
-You should start the restore script with the media containing the
-first volume of the archive mounted. The script will prompt for other
-volumes as they are needed. If the archive is on tape, you don't need
-to rewind the tape to to its beginning---if the tape head is
-positioned past the beginning of the archive, the script will rewind
-the tape as needed. @xref{Media}, for a discussion of tape
-positioning.
+@quotation
+@strong{Please Note:} Always use @option{--sparse} when performing file
+system backups, to avoid archiving the expanded forms of files stored
+sparsely in the system.
+
+Even if your system has no sparse files currently, some may be
+created in the future. If you use @option{--sparse} while making file
+system backups as a matter of course, you can be assured the archive
+will never take more space on the media than the files take on disk
+(otherwise, archiving a disk filled with sparse files might take
+hundreds of tapes). @FIXME-xref{incremental when node name is set.}
+@end quotation
+
+@command{tar} ignores the @option{--sparse} option when reading an archive.
+
+@table @option
+@item --sparse
+@itemx -S
+Files stored sparsely in the file system are represented sparsely in
+the archive. Use in conjunction with write operations.
+@end table
-If you specify @samp{+all} as the @var{files} argument, the
-@code{restore} script extracts all the files in the archived file
-system into the active file system.
+However, users should be well aware that at archive creation time,
+@GNUTAR{} still has to read whole disk file to
+locate the @dfn{holes}, and so, even if sparse files use little space
+on disk and in the archive, they may sometimes require inordinate
+amount of time for reading and examining all-zero blocks of a file.
+Although it works, it's painfully slow for a large (sparse) file, even
+though the resulting tar archive may be small. (One user reports that
+dumping a @file{core} file of over 400 megabytes, but with only about
+3 megabytes of actual data, took about 9 minutes on a Sun Sparcstation
+ELC, with full CPU utilization.)
+
+This reading is required in all cases and is not related to the fact
+the @option{--sparse} option is used or not, so by merely @emph{not}
+using the option, you are not saving time@footnote{Well! We should say
+the whole truth, here. When @option{--sparse} is selected while creating
+an archive, the current @command{tar} algorithm requires sparse files to be
+read twice, not once. We hope to develop a new archive format for saving
+sparse files in which one pass will be sufficient.}.
+
+Programs like @command{dump} do not have to read the entire file; by
+examining the file system directly, they can determine in advance
+exactly where the holes are and thus avoid reading through them. The
+only data it need read are the actual allocated data blocks.
+@GNUTAR{} uses a more portable and straightforward
+archiving approach, it would be fairly difficult that it does
+otherwise. Elizabeth Zwicky writes to @file{comp.unix.internals}, on
+1990-12-10:
@quotation
-@strong{Warning:}The script will delete files from the active file
-system if they were not in the file system when the archive was made.
+What I did say is that you cannot tell the difference between a hole and an
+equivalent number of nulls without reading raw blocks. @code{st_blocks} at
+best tells you how many holes there are; it doesn't tell you @emph{where}.
+Just as programs may, conceivably, care what @code{st_blocks} is (care
+to name one that does?), they may also care where the holes are (I have
+no examples of this one either, but it's equally imaginable).
+
+I conclude from this that good archivers are not portable. One can
+arguably conclude that if you want a portable program, you can in good
+conscience restore files with as many holes as possible, since you can't
+get it right.
@end quotation
-@xref{incremental and listed-incremental}, for an explanation of how
-the script makes that determination.
-@c this may be an option, not a given
-@end ignore
-
-@node incremental and listed-incremental, Problems, Backup Scripts, Backups and Restoration
-@section The @code{+incremental} and @code{+listed-incremental} Options
-
-@samp{+incremental} is used in conjunction with @samp{+create},
-@samp{+extract} or @samp{+list} when backing up and restoring file
-systems. An archive cannot be extracted or listed with the
-@samp{+incremental} option specified unless it was created with the
-option specified. This option should only be used by a script, not by
-the user, and is usually disregarded in favor of
-@samp{+listed-incremental}, which is described below.
-
-@samp{+incremental} in conjunction with @samp{+create} causes
-@code{tar} to write, at the beginning of the archive, an entry for
-each of the directories that will be archived. The entry for a
-directory includes a list of all the files in the directory at the
-time the archive was created and a flag for each file indicating
-whether or not the file is going to be put in the archive.
-
-Note that this option causes @code{tar} to create a non-standard
-archive that may not be readable by non-GNU versions of the @code{tar}
-program.
-
-@samp{+incremental} in conjunction with @samp{+extract} causes
-@code{tar} to read the lists of directory contents previously stored
-in the archive, @emph{delete} files in the file system that did not
-exist in their directories when the archive was created, and then
-extract the files in the archive.
-
-This behavior is convenient when restoring a damaged file system from
-a succession of incremental backups: it restores the entire state of
-the file system to that which obtained when the backup was made. If
-@samp{+incremental} isn't specified, the file system will probably
-fill up with files that shouldn't exist any more.
-
-@samp{+incremental} in conjunction with @samp{+list}, causes
-@code{tar} to print, for each directory in the archive, the list of
-files in that directory at the time the archive was created. This
-information is put out in a format that is not easy for humans to
-read, but which is unambiguous for a program: each file name is
-preceded by either a @samp{Y} if the file is present in the archive,
-an @samp{N} if the file is not included in the archive, or a @samp{D}
-if the file is a directory (and is included in the archive). Each
-file name is terminated by a null character. The last file is followed
-by an additional null and a newline to indicate the end of the data.
-
-@samp{+listed-incremental}=@var{file} acts like @samp{+incremental},
-but when used in conjunction with @samp{+create} will also cause
-@code{tar} to use the file @var{file}, which contains information
-about the state of the file system at the time of the last backup, to
-decide which files to include in the archive being created. That file
-will then be updated by @code{tar}. If the file @var{file} does not
-exist when this option is specified, @code{tar} will create it, and
-include all appropriate files in the archive.
-
-The file @var{file}, which is archive independent, contains the date
-it was last modified and a list of devices, inode numbers and
-directory names. @code{tar} will archive files with newer mod dates
-or inode change times, and directories with an unchanged inode number
-and device but a changed directory name. The file is updated after
-the files to be archived are determined, but before the new archive is
-actually created.
-
-@c <<< this section needs to be written
-@node Problems, , incremental and listed-incremental, Backups and Restoration
-@section Some Common Problems and their Solutions
+@node Attributes
+@section Handling File Attributes
+@UNREVISED
+
+When @command{tar} reads files, it updates their access times. To
+avoid this, use the @option{--atime-preserve[=METHOD]} option, which can either
+reset the access time retroactively or avoid changing it in the first
+place.
+
+Handling of file attributes
+
+@table @option
+@opindex atime-preserve
+@item --atime-preserve
+@itemx --atime-preserve=replace
+@itemx --atime-preserve=system
+Preserve the access times of files that are read. This works only for
+files that you own, unless you have superuser privileges.
+
+@option{--atime-preserve=replace} works on most systems, but it also
+restores the data modification time and updates the status change
+time. Hence it doesn't interact with incremental dumps nicely
+(@pxref{Backups}), and it can set access or data modification times
+incorrectly if other programs access the file while @command{tar} is
+running.
+
+@option{--atime-preserve=system} avoids changing the access time in
+the first place, if the operating system supports this.
+Unfortunately, this may or may not work on any given operating system
+or file system. If @command{tar} knows for sure it won't work, it
+complains right away.
+
+Currently @option{--atime-preserve} with no operand defaults to
+@option{--atime-preserve=replace}, but this is intended to change to
+@option{--atime-preserve=system} when the latter is better-supported.
+
+@opindex touch
+@item -m
+@itemx --touch
+Do not extract data modification time.
-errors from system:
-permission denied
-no such file or directory
-not owner
+When this option is used, @command{tar} leaves the data modification times
+of the files it extracts as the times when the files were extracted,
+instead of setting it to the times recorded in the archive.
-errors from tar:
-directory checksum error
-header format error
+This option is meaningless with @option{--list} (@option{-t}).
-errors from media/system:
-i/o error
-device busy
+@opindex same-owner
+@item --same-owner
+Create extracted files with the same ownership they have in the
+archive.
-@node Media, Quick Reference, Backups and Restoration, Top
-@chapter Tapes and Other Archive Media
+This is the default behavior for the superuser,
+so this option is meaningful only for non-root users, when @command{tar}
+is executed on those systems able to give files away. This is
+considered as a security flaw by many people, at least because it
+makes quite difficult to correctly account users for the disk space
+they occupy. Also, the @code{suid} or @code{sgid} attributes of
+files are easily and silently lost when files are given away.
+
+When writing an archive, @command{tar} writes the user id and user name
+separately. If it can't find a user name (because the user id is not
+in @file{/etc/passwd}), then it does not write one. When restoring,
+and doing a @code{chmod} like when you use @option{--same-permissions},
+@FIXME{same-owner?}it tries to look the name (if one was written)
+up in @file{/etc/passwd}. If it fails, then it uses the user id
+stored in the archive instead.
+
+@opindex no-same-owner
+@item --no-same-owner
+@itemx -o
+Do not attempt to restore ownership when extracting. This is the
+default behavior for ordinary users, so this option has an effect
+only for the superuser.
+
+@opindex numeric-owner
+@item --numeric-owner
+The @option{--numeric-owner} option allows (ANSI) archives to be written
+without user/group name information or such information to be ignored
+when extracting. It effectively disables the generation and/or use
+of user/group name information. This option forces extraction using
+the numeric ids from the archive, ignoring the names.
+
+This is useful in certain circumstances, when restoring a backup from
+an emergency floppy with different passwd/group files for example.
+It is otherwise impossible to extract files with the right ownerships
+if the password file in use during the extraction does not match the
+one belonging to the file system(s) being extracted. This occurs,
+for example, if you are restoring your files after a major crash and
+had booted from an emergency floppy with no password file or put your
+disk into another machine to do the restore.
+
+The numeric ids are @emph{always} saved into @command{tar} archives.
+The identifying names are added at create time when provided by the
+system, unless @option{--old-archive} (@option{-o}) is used. Numeric ids could be
+used when moving archives between a collection of machines using
+a centralized management for attribution of numeric ids to users
+and groups. This is often made through using the NIS capabilities.
+
+When making a @command{tar} file for distribution to other sites, it
+is sometimes cleaner to use a single owner for all files in the
+distribution, and nicer to specify the write permission bits of the
+files as stored in the archive independently of their actual value on
+the file system. The way to prepare a clean distribution is usually
+to have some Makefile rule creating a directory, copying all needed
+files in that directory, then setting ownership and permissions as
+wanted (there are a lot of possible schemes), and only then making a
+@command{tar} archive out of this directory, before cleaning
+everything out. Of course, we could add a lot of options to
+@GNUTAR{} for fine tuning permissions and ownership.
+This is not the good way, I think. @GNUTAR{} is
+already crowded with options and moreover, the approach just explained
+gives you a great deal of control already.
+
+@opindex same-permissions, short description
+@opindex preserve-permissions, short description
+@item -p
+@itemx --same-permissions
+@itemx --preserve-permissions
+Extract all protection information.
-Archives are usually written on dismountable media---tape cartridges,
-mag tapes, or floppy disks.
+This option causes @command{tar} to set the modes (access permissions) of
+extracted files exactly as recorded in the archive. If this option
+is not used, the current @code{umask} setting limits the permissions
+on extracted files. This option is by default enabled when
+@command{tar} is executed by a superuser.
-The amount of data a tape or disk holds depends not only on its size,
-but also on how it is formatted. A 2400 foot long reel of mag tape
-holds 40 megabytes of data when formated at 1600 bits per inch. The
-physically smaller EXABYTE tape cartridge holds 2.3 gigabytes.
-Magnetic media are re-usable---once the archive on a tape is no longer
-needed, the archive can be erased and the tape or disk used over.
-Media quality does deteriorate with use, however. Most tapes or disks
-should be disgarded when they begin to produce data errors. EXABYTE
-tape cartridges should be disgarded when they generate an @dfn{error
-count} (number of non-usable bits) of more than 10k.
+This option is meaningless with @option{--list} (@option{-t}).
-Magnetic media are written and erased using magnetic fields, and
-should be protected from such fields to avoid damage to stored data.
-Sticking a floppy disk to a filing cabinet using a magnet is probably
-not a good idea.
+@opindex preserve
+@item --preserve
+Same as both @option{--same-permissions} and @option{--same-order}.
+The @option{--preserve} option has no equivalent short option name.
+It is equivalent to @option{--same-permissions} plus @option{--same-order}.
-@menu
-* Write Protection:: Write Protection
-* Tape Positioning:: Tape Positions and Tape Marks
-@end menu
+@FIXME{I do not see the purpose of such an option. (Neither I. FP.)}
-@node Write Protection, Tape Positioning, Media, Media
-@section Write Protection
+@end table
-All tapes and disks can be @dfn{write protected}, to protect data on
-them from being changed. Once an archive is written, you should write
-protect the media to prevent the archive from being accidently
-overwritten or deleted. (This will protect the archive from being
-changed with a tape or floppy drive---it will not protect it from
-magnet fields or other physical hazards).
+@node Standard
+@section Basic Tar Format
+@UNREVISED
-The write protection device itself is usually an integral part of the
-physical media, and can be a two position (write enabled/write
-disabled) switch, a notch which can be popped out or covered, a ring
-which can be removed from the center of a tape reel, or some other
-changeable feature.
+While an archive may contain many files, the archive itself is a
+single ordinary file. Like any other file, an archive file can be
+written to a storage device such as a tape or disk, sent through a
+pipe or over a network, saved on the active file system, or even
+stored in another archive. An archive file is not easy to read or
+manipulate without using the @command{tar} utility or Tar mode in
+@acronym{GNU} Emacs.
-@node Tape Positioning, , Write Protection, Media
-@section Tape Positions and Tape Marks
+Physically, an archive consists of a series of file entries terminated
+by an end-of-archive entry, which consists of two 512 blocks of zero
+bytes. A file
+entry usually describes one of the files in the archive (an
+@dfn{archive member}), and consists of a file header and the contents
+of the file. File headers contain file names and statistics, checksum
+information which @command{tar} uses to detect file corruption, and
+information about file types.
+
+Archives are permitted to have more than one member with the same
+member name. One way this situation can occur is if more than one
+version of a file has been stored in the archive. For information
+about adding new versions of a file to an archive, see @ref{update}.
+@FIXME-xref{To learn more about having more than one archive member with the
+same name, see -backup node, when it's written.}
+
+In addition to entries describing archive members, an archive may
+contain entries which @command{tar} itself uses to store information.
+@xref{label}, for an example of such an archive entry.
+
+A @command{tar} archive file contains a series of blocks. Each block
+contains @code{BLOCKSIZE} bytes. Although this format may be thought
+of as being on magnetic tape, other media are often used.
+
+Each file archived is represented by a header block which describes
+the file, followed by zero or more blocks which give the contents
+of the file. At the end of the archive file there are two 512-byte blocks
+filled with binary zeros as an end-of-file marker. A reasonable system
+should write such end-of-file marker at the end of an archive, but
+must not assume that such a block exists when reading an archive. In
+particular @GNUTAR{} always issues a warning if it does not encounter it.
+
+The blocks may be @dfn{blocked} for physical I/O operations.
+Each record of @var{n} blocks (where @var{n} is set by the
+@option{--blocking-factor=@var{512-size}} (@option{-b @var{512-size}}) option to @command{tar}) is written with a single
+@w{@samp{write ()}} operation. On magnetic tapes, the result of
+such a write is a single record. When writing an archive,
+the last record of blocks should be written at the full size, with
+blocks after the zero block containing all zeros. When reading
+an archive, a reasonable system should properly handle an archive
+whose last record is shorter than the rest, or which contains garbage
+records after a zero block.
+
+The header block is defined in C as follows. In the @GNUTAR{}
+distribution, this is part of file @file{src/tar.h}:
+
+@smallexample
+@include header.texi
+@end smallexample
+
+All characters in header blocks are represented by using 8-bit
+characters in the local variant of ASCII. Each field within the
+structure is contiguous; that is, there is no padding used within
+the structure. Each character on the archive medium is stored
+contiguously.
+
+Bytes representing the contents of files (after the header block
+of each file) are not translated in any way and are not constrained
+to represent characters in any character set. The @command{tar} format
+does not distinguish text files from binary files, and no translation
+of file contents is performed.
-Just as archives can store more than one file from the file system,
-tapes can store more than one archive file. To keep track of where
-archive files (or any other type of file stored on tape) begin and
-end, tape archive devices write magnetic @dfn{tape marks} on the
-archive media. Tape drives write one tape mark between files,
-two at the end of all the file entries.
+The @code{name}, @code{linkname}, @code{magic}, @code{uname}, and
+@code{gname} are null-terminated character strings. All other fields
+are zero-filled octal numbers in ASCII. Each numeric field of width
+@var{w} contains @var{w} minus 1 digits, and a null.
+
+The @code{name} field is the file name of the file, with directory names
+(if any) preceding the file name, separated by slashes.
+
+@FIXME{how big a name before field overflows?}
+
+The @code{mode} field provides nine bits specifying file permissions
+and three bits to specify the Set UID, Set GID, and Save Text
+(@dfn{sticky}) modes. Values for these bits are defined above.
+When special permissions are required to create a file with a given
+mode, and the user restoring files from the archive does not hold such
+permissions, the mode bit(s) specifying those special permissions
+are ignored. Modes which are not supported by the operating system
+restoring files from the archive will be ignored. Unsupported modes
+should be faked up when creating or updating an archive; e.g., the
+group permission could be copied from the @emph{other} permission.
+
+The @code{uid} and @code{gid} fields are the numeric user and group
+ID of the file owners, respectively. If the operating system does
+not support numeric user or group IDs, these fields should be ignored.
+
+The @code{size} field is the size of the file in bytes; linked files
+are archived with this field specified as zero. @FIXME-xref{Modifiers, in
+particular the @option{--incremental} (@option{-G}) option.}
+
+The @code{mtime} field is the data modification time of the file at
+the time it was archived. It is the ASCII representation of the octal
+value of the last time the file's contents were modified, represented
+as an integer number of
+seconds since January 1, 1970, 00:00 Coordinated Universal Time.
+
+The @code{chksum} field is the ASCII representation of the octal value
+of the simple sum of all bytes in the header block. Each 8-bit
+byte in the header is added to an unsigned integer, initialized to
+zero, the precision of which shall be no less than seventeen bits.
+When calculating the checksum, the @code{chksum} field is treated as
+if it were all blanks.
+
+The @code{typeflag} field specifies the type of file archived. If a
+particular implementation does not recognize or permit the specified
+type, the file will be extracted as if it were a regular file. As this
+action occurs, @command{tar} issues a warning to the standard error.
+
+The @code{atime} and @code{ctime} fields are used in making incremental
+backups; they store, respectively, the particular file's access and
+status change times.
+
+The @code{offset} is used by the @option{--multi-volume} (@option{-M}) option, when
+making a multi-volume archive. The offset is number of bytes into
+the file that we need to restart at to continue the file on the next
+tape, i.e., where we store the location that a continued file is
+continued at.
+
+The following fields were added to deal with sparse files. A file
+is @dfn{sparse} if it takes in unallocated blocks which end up being
+represented as zeros, i.e., no useful data. A test to see if a file
+is sparse is to look at the number blocks allocated for it versus the
+number of characters in the file; if there are fewer blocks allocated
+for the file than would normally be allocated for a file of that
+size, then the file is sparse. This is the method @command{tar} uses to
+detect a sparse file, and once such a file is detected, it is treated
+differently from non-sparse files.
+
+Sparse files are often @code{dbm} files, or other database-type files
+which have data at some points and emptiness in the greater part of
+the file. Such files can appear to be very large when an @samp{ls
+-l} is done on them, when in truth, there may be a very small amount
+of important data contained in the file. It is thus undesirable
+to have @command{tar} think that it must back up this entire file, as
+great quantities of room are wasted on empty blocks, which can lead
+to running out of room on a tape far earlier than is necessary.
+Thus, sparse files are dealt with so that these empty blocks are
+not written to the tape. Instead, what is written to the tape is a
+description, of sorts, of the sparse file: where the holes are, how
+big the holes are, and how much data is found at the end of the hole.
+This way, the file takes up potentially far less room on the tape,
+and when the file is extracted later on, it will look exactly the way
+it looked beforehand. The following is a description of the fields
+used to handle a sparse file:
+
+The @code{sp} is an array of @code{struct sparse}. Each @code{struct
+sparse} contains two 12-character strings which represent an offset
+into the file and a number of bytes to be written at that offset.
+The offset is absolute, and not relative to the offset in preceding
+array element.
+
+The header can hold four of these @code{struct sparse} at the moment;
+if more are needed, they are not stored in the header.
+
+The @code{isextended} flag is set when an @code{extended_header}
+is needed to deal with a file. Note that this means that this flag
+can only be set when dealing with a sparse file, and it is only set
+in the event that the description of the file will not fit in the
+allotted room for sparse structures in the header. In other words,
+an extended_header is needed.
+
+The @code{extended_header} structure is used for sparse files which
+need more sparse structures than can fit in the header. The header can
+fit 4 such structures; if more are needed, the flag @code{isextended}
+gets set and the next block is an @code{extended_header}.
+
+Each @code{extended_header} structure contains an array of 21
+sparse structures, along with a similar @code{isextended} flag
+that the header had. There can be an indeterminate number of such
+@code{extended_header}s to describe a sparse file.
+
+@table @asis
+
+@item @code{REGTYPE}
+@itemx @code{AREGTYPE}
+These flags represent a regular file. In order to be compatible
+with older versions of @command{tar}, a @code{typeflag} value of
+@code{AREGTYPE} should be silently recognized as a regular file.
+New archives should be created using @code{REGTYPE}. Also, for
+backward compatibility, @command{tar} treats a regular file whose name
+ends with a slash as a directory.
+
+@item @code{LNKTYPE}
+This flag represents a file linked to another file, of any type,
+previously archived. Such files are identified in Unix by each
+file having the same device and inode number. The linked-to name is
+specified in the @code{linkname} field with a trailing null.
+
+@item @code{SYMTYPE}
+This represents a symbolic link to another file. The linked-to name
+is specified in the @code{linkname} field with a trailing null.
+
+@item @code{CHRTYPE}
+@itemx @code{BLKTYPE}
+These represent character special files and block special files
+respectively. In this case the @code{devmajor} and @code{devminor}
+fields will contain the major and minor device numbers respectively.
+Operating systems may map the device specifications to their own
+local specification, or may ignore the entry.
+
+@item @code{DIRTYPE}
+This flag specifies a directory or sub-directory. The directory
+name in the @code{name} field should end with a slash. On systems where
+disk allocation is performed on a directory basis, the @code{size} field
+will contain the maximum number of bytes (which may be rounded to
+the nearest disk block allocation unit) which the directory may
+hold. A @code{size} field of zero indicates no such limiting. Systems
+which do not support limiting in this manner should ignore the
+@code{size} field.
+
+@item @code{FIFOTYPE}
+This specifies a FIFO special file. Note that the archiving of a
+FIFO file archives the existence of this file and not its contents.
+
+@item @code{CONTTYPE}
+This specifies a contiguous file, which is the same as a normal
+file except that, in operating systems which support it, all its
+space is allocated contiguously on the disk. Operating systems
+which do not allow contiguous allocation should silently treat this
+type as a normal file.
+
+@item @code{A} @dots{} @code{Z}
+These are reserved for custom implementations. Some of these are
+used in the @acronym{GNU} modified format, as described below.
+
+@end table
+
+Other values are reserved for specification in future revisions of
+the P1003 standard, and should not be used by any @command{tar} program.
+
+The @code{magic} field indicates that this archive was output in
+the P1003 archive format. If this field contains @code{TMAGIC},
+the @code{uname} and @code{gname} fields will contain the ASCII
+representation of the owner and group of the file respectively.
+If found, the user and group IDs are used rather than the values in
+the @code{uid} and @code{gid} fields.
+
+For references, see ISO/IEC 9945-1:1990 or IEEE Std 1003.1-1990, pages
+169-173 (section 10.1) for @cite{Archive/Interchange File Format}; and
+IEEE Std 1003.2-1992, pages 380-388 (section 4.48) and pages 936-940
+(section E.4.48) for @cite{pax - Portable archive interchange}.
+
+@node Extensions
+@section @acronym{GNU} Extensions to the Archive Format
+@UNREVISED
+
+The @acronym{GNU} format uses additional file types to describe new types of
+files in an archive. These are listed below.
+
+@table @code
+@item GNUTYPE_DUMPDIR
+@itemx 'D'
+This represents a directory and a list of files created by the
+@option{--incremental} (@option{-G}) option. The @code{size} field gives the total
+size of the associated list of files. Each file name is preceded by
+either a @samp{Y} (the file should be in this archive) or an @samp{N}.
+(The file is a directory, or is not stored in the archive.) Each file
+name is terminated by a null. There is an additional null after the
+last file name.
+
+@item GNUTYPE_MULTIVOL
+@itemx 'M'
+This represents a file continued from another volume of a multi-volume
+archive created with the @option{--multi-volume} (@option{-M}) option. The original
+type of the file is not given here. The @code{size} field gives the
+maximum size of this piece of the file (assuming the volume does
+not end before the file is written out). The @code{offset} field
+gives the offset from the beginning of the file where this part of
+the file begins. Thus @code{size} plus @code{offset} should equal
+the original size of the file.
+
+@item GNUTYPE_SPARSE
+@itemx 'S'
+This flag indicates that we are dealing with a sparse file. Note
+that archiving a sparse file requires special operations to find
+holes in the file, which mark the positions of these holes, along
+with the number of bytes of data to be found after the hole.
+
+@item GNUTYPE_VOLHDR
+@itemx 'V'
+This file type is used to mark the volume header that was given with
+the @option{--label=@var{archive-label}} (@option{-V @var{archive-label}}) option when the archive was created. The @code{name}
+field contains the @code{name} given after the @option{--label=@var{archive-label}} (@option{-V @var{archive-label}}) option.
+The @code{size} field is zero. Only the first file in each volume
+of an archive should have this type.
-If you think of data as a series of "0000"'s, and tape marks as "x"'s,
-a tape might look like the following:
+@end table
-@example
-0000x000000x00000x00x00000xx-------------------------
-@end example
+You may have trouble reading a @acronym{GNU} format archive on a
+non-@acronym{GNU} system if the options @option{--incremental} (@option{-G}),
+@option{--multi-volume} (@option{-M}), @option{--sparse} (@option{-S}), or @option{--label=@var{archive-label}} (@option{-V @var{archive-label}}) were
+used when writing the archive. In general, if @command{tar} does not
+use the @acronym{GNU}-added fields of the header, other versions of
+@command{tar} should be able to read the archive. Otherwise, the
+@command{tar} program will give an error, the most likely one being a
+checksum error.
+
+@node cpio
+@section Comparison of @command{tar} and @command{cpio}
+@UNREVISED
+
+@FIXME{Reorganize the following material}
+
+The @command{cpio} archive formats, like @command{tar}, do have maximum
+pathname lengths. The binary and old ASCII formats have a max path
+length of 256, and the new ASCII and CRC ASCII formats have a max
+path length of 1024. @acronym{GNU} @command{cpio} can read and write archives
+with arbitrary pathname lengths, but other @command{cpio} implementations
+may crash unexplainedly trying to read them.
+
+@command{tar} handles symbolic links in the form in which it comes in BSD;
+@command{cpio} doesn't handle symbolic links in the form in which it comes
+in System V prior to SVR4, and some vendors may have added symlinks
+to their system without enhancing @command{cpio} to know about them.
+Others may have enhanced it in a way other than the way I did it
+at Sun, and which was adopted by AT&T (and which is, I think, also
+present in the @command{cpio} that Berkeley picked up from AT&T and put
+into a later BSD release---I think I gave them my changes).
+
+(SVR4 does some funny stuff with @command{tar}; basically, its @command{cpio}
+can handle @command{tar} format input, and write it on output, and it
+probably handles symbolic links. They may not have bothered doing
+anything to enhance @command{tar} as a result.)
+
+@command{cpio} handles special files; traditional @command{tar} doesn't.
+
+@command{tar} comes with V7, System III, System V, and BSD source;
+@command{cpio} comes only with System III, System V, and later BSD
+(4.3-tahoe and later).
+
+@command{tar}'s way of handling multiple hard links to a file can handle
+file systems that support 32-bit inumbers (e.g., the BSD file system);
+@command{cpio}s way requires you to play some games (in its "binary"
+format, i-numbers are only 16 bits, and in its "portable ASCII" format,
+they're 18 bits---it would have to play games with the "file system ID"
+field of the header to make sure that the file system ID/i-number pairs
+of different files were always different), and I don't know which
+@command{cpio}s, if any, play those games. Those that don't might get
+confused and think two files are the same file when they're not, and
+make hard links between them.
+
+@command{tar}s way of handling multiple hard links to a file places only
+one copy of the link on the tape, but the name attached to that copy
+is the @emph{only} one you can use to retrieve the file; @command{cpio}s
+way puts one copy for every link, but you can retrieve it using any
+of the names.
-Tape devices read and write tapes using a read/write @dfn{tape
-head}---a physical part of the device which can only access one point
-on the tape at a time. When you use @code{tar} to read or write
-archive data from a tape device, the device will begin reading or
-writing from wherever on the tape the tape head happens to be,
-regardless of which archive or what part of the archive the tape head
-is on. Before writing an archive, you should make sure that no data
-on the tape will be overwritten (unless it is no longer needed).
-Before reading an archive, you should make sure the tape head is at
-the beginning of the archive you want to read. (The @code{restore}
-script will find the archive automatically. @xref{Scripted
-Restoration}). @xref{mt}, for an explanation of the tape moving
-utility.
+@quotation
+What type of check sum (if any) is used, and how is this calculated.
+@end quotation
-If you want to add new archive file entries to a tape, you should
-advance the tape to the end of the existing file entries, backspace
-over the last tape mark, and write the new archive file. If you were
-to add two archives to the example above, the tape might look like the
-following:
+See the attached manual pages for @command{tar} and @command{cpio} format.
+@command{tar} uses a checksum which is the sum of all the bytes in the
+@command{tar} header for a file; @command{cpio} uses no checksum.
-@example
-0000x000000x00000x00x00000x000x0000xx----------------
-@end example
+@quotation
+If anyone knows why @command{cpio} was made when @command{tar} was present
+at the unix scene,
+@end quotation
-@menu
-* mt:: The @code{mt} Utility
-@end menu
+It wasn't. @command{cpio} first showed up in PWB/UNIX 1.0; no
+generally-available version of UNIX had @command{tar} at the time. I don't
+know whether any version that was generally available @emph{within AT&T}
+had @command{tar}, or, if so, whether the people within AT&T who did
+@command{cpio} knew about it.
-@node mt, , Tape Positioning, Tape Positioning
-@subsection The @code{mt} Utility
+On restore, if there is a corruption on a tape @command{tar} will stop at
+that point, while @command{cpio} will skip over it and try to restore the
+rest of the files.
-<<< is it true that this only works on non-block devices? should
-<<< explain the difference, xref to block-size (fixed or variable).
+The main difference is just in the command syntax and header format.
-You can use the @code{mt} utility to advance or rewind a tape past a
-specified number of archive files on the tape. This will allow you to
-move to the beginning of an archive before extracting or reading it,
-or to the end of all the archives before writing a new one.
-@c why isn't there an "advance 'til you find two tape marks together"?
+@command{tar} is a little more tape-oriented in that everything is blocked
+to start on a record boundary.
-The syntax of the @code{mt} command is:
+@quotation
+Is there any differences between the ability to recover crashed
+archives between the two of them. (Is there any chance of recovering
+crashed archives at all.)
+@end quotation
-@example
-mt [-f @var{tapename}] @var{operation} [@var{number}]
-@end example
+Theoretically it should be easier under @command{tar} since the blocking
+lets you find a header with some variation of @samp{dd skip=@var{nn}}.
+However, modern @command{cpio}'s and variations have an option to just
+search for the next file header after an error with a reasonable chance
+of resyncing. However, lots of tape driver software won't allow you to
+continue past a media error which should be the only reason for getting
+out of sync unless a file changed sizes while you were writing the
+archive.
-where @var{tapename} is the name of the tape device, @var{number} is
-the number of times an operation is performed (with a default of one),
-and @var{operation} is one of the following:
+@quotation
+If anyone knows why @command{cpio} was made when @command{tar} was present
+at the unix scene, please tell me about this too.
+@end quotation
-@table @code
-@item eof
-@itemx weof
-Writes @var{number} tape marks at the current position on the tape.
+Probably because it is more media efficient (by not blocking everything
+and using only the space needed for the headers where @command{tar}
+always uses 512 bytes per file header) and it knows how to archive
+special files.
+You might want to look at the freely available alternatives. The
+major ones are @command{afio}, @GNUTAR{}, and
+@command{pax}, each of which have their own extensions with some
+backwards compatibility.
-@item fsf
-Moves tape position forward @var{number} files.
+Sparse files were @command{tar}red as sparse files (which you can
+easily test, because the resulting archive gets smaller, and
+@acronym{GNU} @command{cpio} can no longer read it).
+@node Media
+@chapter Tapes and Other Archive Media
+@UNREVISED
-@item bsf
-Moves tape position back @var{number} files.
+A few special cases about tape handling warrant more detailed
+description. These special cases are discussed below.
+Many complexities surround the use of @command{tar} on tape drives. Since
+the creation and manipulation of archives located on magnetic tape was
+the original purpose of @command{tar}, it contains many features making
+such manipulation easier.
-@item rewind
-Rewinds the tape. (Ignores @var{number}).
+Archives are usually written on dismountable media---tape cartridges,
+mag tapes, or floppy disks.
+The amount of data a tape or disk holds depends not only on its size,
+but also on how it is formatted. A 2400 foot long reel of mag tape
+holds 40 megabytes of data when formatted at 1600 bits per inch. The
+physically smaller EXABYTE tape cartridge holds 2.3 gigabytes.
-@item offline
-@itemx rewoff1
-Rewinds the tape and takes the tape device off-line. (Ignores @var{number}).
+Magnetic media are re-usable---once the archive on a tape is no longer
+needed, the archive can be erased and the tape or disk used over.
+Media quality does deteriorate with use, however. Most tapes or disks
+should be discarded when they begin to produce data errors. EXABYTE
+tape cartridges should be discarded when they generate an @dfn{error
+count} (number of non-usable bits) of more than 10k.
+Magnetic media are written and erased using magnetic fields, and
+should be protected from such fields to avoid damage to stored data.
+Sticking a floppy disk to a filing cabinet using a magnet is probably
+not a good idea.
-@item status
-Prints status information about the tape unit.
+@menu
+* Device:: Device selection and switching
+* Remote Tape Server::
+* Common Problems and Solutions::
+* Blocking:: Blocking
+* Many:: Many archives on one tape
+* Using Multiple Tapes:: Using Multiple Tapes
+* label:: Including a Label in the Archive
+* verify::
+* Write Protection::
+@end menu
+
+@node Device
+@section Device Selection and Switching
+@UNREVISED
+
+@table @option
+@item -f [@var{hostname}:]@var{file}
+@itemx --file=[@var{hostname}:]@var{file}
+Use archive file or device @var{file} on @var{hostname}.
@end table
-<<< is there a better way to frob the spacing on the list? -ringo
-If you don't specify a @var{tapename}, @code{mt} uses the environment
-variable TAPE; if TAPE does not exist, @code{mt} uses the device
-@file{/dev/rmt12}.
+This option is used to specify the file name of the archive @command{tar}
+works on.
+
+If the file name is @samp{-}, @command{tar} reads the archive from standard
+input (when listing or extracting), or writes it to standard output
+(when creating). If the @samp{-} file name is given when updating an
+archive, @command{tar} will read the original archive from its standard
+input, and will write the entire new archive to its standard output.
+
+If the file name contains a @samp{:}, it is interpreted as
+@samp{hostname:file name}. If the @var{hostname} contains an @dfn{at}
+sign (@samp{@@}), it is treated as @samp{user@@hostname:file name}. In
+either case, @command{tar} will invoke the command @command{rsh} (or
+@command{remsh}) to start up an @command{/usr/libexec/rmt} on the remote
+machine. If you give an alternate login name, it will be given to the
+@command{rsh}.
+Naturally, the remote machine must have an executable
+@command{/usr/libexec/rmt}. This program is free software from the
+University of California, and a copy of the source code can be found
+with the sources for @command{tar}; it's compiled and installed by default.
+The exact path to this utility is determined when configuring the package.
+It is @file{@var{prefix}/libexec/rmt}, where @var{prefix} stands for
+your installation prefix. This location may also be overridden at
+runtime by using @option{rmt-command=@var{command}} option (@xref{Option Summary,
+---rmt-command}, for detailed description of this option. @xref{Remote
+Tape Server}, for the description of @command{rmt} command).
+
+If this option is not given, but the environment variable @env{TAPE}
+is set, its value is used; otherwise, old versions of @command{tar}
+used a default archive name (which was picked when @command{tar} was
+compiled). The default is normally set up to be the @dfn{first} tape
+drive or other transportable I/O medium on the system.
+
+Starting with version 1.11.5, @GNUTAR{} uses
+standard input and standard output as the default device, and I will
+not try anymore supporting automatic device detection at installation
+time. This was failing really in too many cases, it was hopeless.
+This is now completely left to the installer to override standard
+input and standard output for default device, if this seems
+preferable. Further, I think @emph{most} actual usages of
+@command{tar} are done with pipes or disks, not really tapes,
+cartridges or diskettes.
+
+Some users think that using standard input and output is running
+after trouble. This could lead to a nasty surprise on your screen if
+you forget to specify an output file name---especially if you are going
+through a network or terminal server capable of buffering large amounts
+of output. We had so many bug reports in that area of configuring
+default tapes automatically, and so many contradicting requests, that
+we finally consider the problem to be portably intractable. We could
+of course use something like @samp{/dev/tape} as a default, but this
+is @emph{also} running after various kind of trouble, going from hung
+processes to accidental destruction of real tapes. After having seen
+all this mess, using standard input and output as a default really
+sounds like the only clean choice left, and a very useful one too.
+
+@GNUTAR{} reads and writes archive in records, I
+suspect this is the main reason why block devices are preferred over
+character devices. Most probably, block devices are more efficient
+too. The installer could also check for @samp{DEFTAPE} in
+@file{<sys/mtio.h>}.
+
+@table @option
+@opindex force-local, short description
+@item --force-local
+Archive file is local even if it contains a colon.
+
+@opindex rsh-command
+@item --rsh-command=@var{command}
+Use remote @var{command} instead of @command{rsh}. This option exists
+so that people who use something other than the standard @command{rsh}
+(e.g., a Kerberized @command{rsh}) can access a remote device.
+
+When this command is not used, the shell command found when
+the @command{tar} program was installed is used instead. This is
+the first found of @file{/usr/ucb/rsh}, @file{/usr/bin/remsh},
+@file{/usr/bin/rsh}, @file{/usr/bsd/rsh} or @file{/usr/bin/nsh}.
+The installer may have overridden this by defining the environment
+variable @env{RSH} @emph{at installation time}.
+
+@item -[0-7][lmh]
+Specify drive and density.
+
+@opindex multi-volume, short description
+@item -M
+@itemx --multi-volume
+Create/list/extract multi-volume archive.
+
+This option causes @command{tar} to write a @dfn{multi-volume} archive---one
+that may be larger than will fit on the medium used to hold it.
+@xref{Multi-Volume Archives}.
+
+@opindex tape-length, short description
+@item -L @var{num}
+@itemx --tape-length=@var{num}
+Change tape after writing @var{num} x 1024 bytes.
+
+This option might be useful when your tape drivers do not properly
+detect end of physical tapes. By being slightly conservative on the
+maximum tape length, you might avoid the problem entirely.
+
+@opindex info-script, short description
+@opindex new-volume-script, short description
+@item -F @var{file}
+@itemx --info-script=@var{file}
+@itemx --new-volume-script=@var{file}
+Execute @file{file} at end of each tape. This implies
+@option{--multi-volume} (@option{-M}). @xref{info-script}, for a detailed
+description of this option.
+@end table
-@code{mt} returns a 0 exit status when the operation(s) were
-successful, 1 if the command was unrecognized, and 2 if an operation
-failed.
+@node Remote Tape Server
+@section The Remote Tape Server
+
+@cindex remote tape drive
+@pindex rmt
+In order to access the tape drive on a remote machine, @command{tar}
+uses the remote tape server written at the University of California at
+Berkeley. The remote tape server must be installed as
+@file{@var{prefix}/libexec/rmt} on any machine whose tape drive you
+want to use. @command{tar} calls @command{rmt} by running an
+@command{rsh} or @command{remsh} to the remote machine, optionally
+using a different login name if one is supplied.
+
+A copy of the source for the remote tape server is provided. It is
+Copyright @copyright{} 1983 by the Regents of the University of
+California, but can be freely distributed. It is compiled and
+installed by default.
+
+@cindex absolute file names
+Unless you use the @option{--absolute-names} (@option{-P}) option,
+@GNUTAR{} will not allow you to create an archive that contains
+absolute file names (a file name beginning with @samp{/}.) If you try,
+@command{tar} will automatically remove the leading @samp{/} from the
+file names it stores in the archive. It will also type a warning
+message telling you what it is doing.
+
+When reading an archive that was created with a different
+@command{tar} program, @GNUTAR{} automatically
+extracts entries in the archive which have absolute file names as if
+the file names were not absolute. This is an important feature. A
+visitor here once gave a @command{tar} tape to an operator to restore;
+the operator used Sun @command{tar} instead of @GNUTAR{},
+and the result was that it replaced large portions of
+our @file{/bin} and friends with versions from the tape; needless to
+say, we were unhappy about having to recover the file system from
+backup tapes.
+
+For example, if the archive contained a file @file{/usr/bin/computoy},
+@GNUTAR{} would extract the file to @file{usr/bin/computoy},
+relative to the current directory. If you want to extract the files in
+an archive to the same absolute names that they had when the archive
+was created, you should do a @samp{cd /} before extracting the files
+from the archive, or you should either use the @option{--absolute-names}
+option, or use the command @samp{tar -C / @dots{}}.
+
+@cindex Ultrix 3.1 and write failure
+Some versions of Unix (Ultrix 3.1 is known to have this problem),
+can claim that a short write near the end of a tape succeeded,
+when it actually failed. This will result in the -M option not
+working correctly. The best workaround at the moment is to use a
+significantly larger blocking factor than the default 20.
+
+In order to update an archive, @command{tar} must be able to backspace the
+archive in order to reread or rewrite a record that was just read (or
+written). This is currently possible only on two kinds of files: normal
+disk files (or any other file that can be backspaced with @samp{lseek}),
+and industry-standard 9-track magnetic tape (or any other kind of tape
+that can be backspaced with the @code{MTIOCTOP} @code{ioctl}.
+
+This means that the @option{--append}, @option{--concatenate}, and
+@option{--delete} commands will not work on any other kind of file.
+Some media simply cannot be backspaced, which means these commands and
+options will never be able to work on them. These non-backspacing
+media include pipes and cartridge tape drives.
+
+Some other media can be backspaced, and @command{tar} will work on them
+once @command{tar} is modified to do so.
+
+Archives created with the @option{--multi-volume}, @option{--label}, and
+@option{--incremental} (@option{-G}) options may not be readable by other version
+of @command{tar}. In particular, restoring a file that was split over
+a volume boundary will require some careful work with @command{dd}, if
+it can be done at all. Other versions of @command{tar} may also create
+an empty file whose name is that of the volume header. Some versions
+of @command{tar} may create normal files instead of directories archived
+with the @option{--incremental} (@option{-G}) option.
+
+@node Common Problems and Solutions
+@section Some Common Problems and their Solutions
-@c <<< new node on how to find an archive? -ringo
-If you use @code{tar +extract} with the
-@samp{+label=@var{archive-name}} option specified, @code{tar} will
-read an archive label (the tape head has to be positioned on it) and
-print an error if the archive label doesn't match the
-@var{archive-name} specified. @var{archive-name} can be any regular
-expression. If the labels match, @code{tar} extracts the archive.
-@xref{Archive Label}. @xref{Matching Format Parameters}.
-<<< fix cross references
+@ifclear PUBLISH
-@code{tar +list +label} will cause @code{tar} to print the label.
+@format
+errors from system:
+permission denied
+no such file or directory
+not owner
-@c <<< MIB -- program to list all the labels on a tape?
+errors from @command{tar}:
+directory checksum error
+header format error
-@node Quick Reference, Data Format Details, Media, Top
-@appendix A Quick Reference Guide to @code{tar} Operations and Options
-@c put in proper form for appendix. (unnumbered?)
+errors from media/system:
+i/o error
+device busy
+@end format
-@menu
-* Operations:: A Table of Operations
-* Options:: Table of Options
-@end menu
+@end ifclear
-@node Operations, Options, Quick Reference, Quick Reference
-@appendixsec A Table of Operations
-@c add xrefs, note synonyms
+@node Blocking
+@section Blocking
+@UNREVISED
-The operation argument to @code{tar} specifies which action you want to
-take.
+@dfn{Block} and @dfn{record} terminology is rather confused, and it
+is also confusing to the expert reader. On the other hand, readers
+who are new to the field have a fresh mind, and they may safely skip
+the next two paragraphs, as the remainder of this manual uses those
+two terms in a quite consistent way.
-@table @samp
-@item -A
-Adds copies of an archive or archives to the end of another archive.
+John Gilmore, the writer of the public domain @command{tar} from which
+@GNUTAR{} was originally derived, wrote (June 1995):
-@item -c
-Creates a new archive.
+@quotation
+The nomenclature of tape drives comes from IBM, where I believe
+they were invented for the IBM 650 or so. On IBM mainframes, what
+is recorded on tape are tape blocks. The logical organization of
+data is into records. There are various ways of putting records into
+blocks, including @code{F} (fixed sized records), @code{V} (variable
+sized records), @code{FB} (fixed blocked: fixed size records, @var{n}
+to a block), @code{VB} (variable size records, @var{n} to a block),
+@code{VSB} (variable spanned blocked: variable sized records that can
+occupy more than one block), etc. The @code{JCL} @samp{DD RECFORM=}
+parameter specified this to the operating system.
+
+The Unix man page on @command{tar} was totally confused about this.
+When I wrote @code{PD TAR}, I used the historically correct terminology
+(@command{tar} writes data records, which are grouped into blocks).
+It appears that the bogus terminology made it into @acronym{POSIX} (no surprise
+here), and now Fran@,{c}ois has migrated that terminology back
+into the source code too.
+@end quotation
-@item -d
-Compares files in the archive with their counterparts in the file
-system, and reports differences in file size, mode, owner,
-modification date and contents.
+The term @dfn{physical block} means the basic transfer chunk from or
+to a device, after which reading or writing may stop without anything
+being lost. In this manual, the term @dfn{block} usually refers to
+a disk physical block, @emph{assuming} that each disk block is 512
+bytes in length. It is true that some disk devices have different
+physical blocks, but @command{tar} ignore these differences in its own
+format, which is meant to be portable, so a @command{tar} block is always
+512 bytes in length, and @dfn{block} always mean a @command{tar} block.
+The term @dfn{logical block} often represents the basic chunk of
+allocation of many disk blocks as a single entity, which the operating
+system treats somewhat atomically; this concept is only barely used
+in @GNUTAR{}.
+
+The term @dfn{physical record} is another way to speak of a physical
+block, those two terms are somewhat interchangeable. In this manual,
+the term @dfn{record} usually refers to a tape physical block,
+@emph{assuming} that the @command{tar} archive is kept on magnetic tape.
+It is true that archives may be put on disk or used with pipes,
+but nevertheless, @command{tar} tries to read and write the archive one
+@dfn{record} at a time, whatever the medium in use. One record is made
+up of an integral number of blocks, and this operation of putting many
+disk blocks into a single tape block is called @dfn{reblocking}, or
+more simply, @dfn{blocking}. The term @dfn{logical record} refers to
+the logical organization of many characters into something meaningful
+to the application. The term @dfn{unit record} describes a small set
+of characters which are transmitted whole to or by the application,
+and often refers to a line of text. Those two last terms are unrelated
+to what we call a @dfn{record} in @GNUTAR{}.
+
+When writing to tapes, @command{tar} writes the contents of the archive
+in chunks known as @dfn{records}. To change the default blocking
+factor, use the @option{--blocking-factor=@var{512-size}} (@option{-b
+@var{512-size}}) option. Each record will then be composed of
+@var{512-size} blocks. (Each @command{tar} block is 512 bytes.
+@xref{Standard}.) Each file written to the archive uses at least one
+full record. As a result, using a larger record size can result in
+more wasted space for small files. On the other hand, a larger record
+size can often be read and written much more efficiently.
+
+Further complicating the problem is that some tape drives ignore the
+blocking entirely. For these, a larger record size can still improve
+performance (because the software layers above the tape drive still
+honor the blocking), but not as dramatically as on tape drives that
+honor blocking.
+
+When reading an archive, @command{tar} can usually figure out the
+record size on itself. When this is the case, and a non-standard
+record size was used when the archive was created, @command{tar} will
+print a message about a non-standard blocking factor, and then operate
+normally. On some tape devices, however, @command{tar} cannot figure
+out the record size itself. On most of those, you can specify a
+blocking factor (with @option{--blocking-factor}) larger than the
+actual blocking factor, and then use the @option{--read-full-records}
+(@option{-B}) option. (If you specify a blocking factor with
+@option{--blocking-factor} and don't use the
+@option{--read-full-records} option, then @command{tar} will not
+attempt to figure out the recording size itself.) On some devices,
+you must always specify the record size exactly with
+@option{--blocking-factor} when reading, because @command{tar} cannot
+figure it out. In any case, use @option{--list} (@option{-t}) before
+doing any extractions to see whether @command{tar} is reading the archive
+correctly.
+
+@command{tar} blocks are all fixed size (512 bytes), and its scheme for
+putting them into records is to put a whole number of them (one or
+more) into each record. @command{tar} records are all the same size;
+at the end of the file there's a block containing all zeros, which
+is how you tell that the remainder of the last record(s) are garbage.
+
+In a standard @command{tar} file (no options), the block size is 512
+and the record size is 10240, for a blocking factor of 20. What the
+@option{--blocking-factor} option does is sets the blocking factor,
+changing the record size while leaving the block size at 512 bytes.
+20 was fine for ancient 800 or 1600 bpi reel-to-reel tape drives;
+most tape drives these days prefer much bigger records in order to
+stream and not waste tape. When writing tapes for myself, some tend
+to use a factor of the order of 2048, say, giving a record size of
+around one megabyte.
+
+If you use a blocking factor larger than 20, older @command{tar}
+programs might not be able to read the archive, so we recommend this
+as a limit to use in practice. @GNUTAR{}, however,
+will support arbitrarily large record sizes, limited only by the
+amount of virtual memory or the physical characteristics of the tape
+device.
-@item -r
-Adds files to the end of the archive.
+@menu
+* Format Variations:: Format Variations
+* Blocking Factor:: The Blocking Factor of an Archive
+@end menu
-@item -t
-Prints a list of the contents of the archive.
+@node Format Variations
+@subsection Format Variations
+@cindex Format Parameters
+@cindex Format Options
+@cindex Options, archive format specifying
+@cindex Options, format specifying
+@UNREVISED
-@item -x
-Reads files from the archive and writes them into the active file
-system.
+Format parameters specify how an archive is written on the archive
+media. The best choice of format parameters will vary depending on
+the type and number of files being archived, and on the media used to
+store the archive.
-@item -u
-Adds files to the end of the archive, but only if they are newer than
-their counterparts already in the archive, or if they do not already
-exist in the archive.
+To specify format parameters when accessing or creating an archive,
+you can use the options described in the following sections.
+If you do not specify any format parameters, @command{tar} uses
+default parameters. You cannot modify a compressed archive.
+If you create an archive with the @option{--blocking-factor} option
+specified (@pxref{Blocking Factor}), you must specify that
+blocking-factor when operating on the archive. @xref{Formats}, for other
+examples of format parameter considerations.
+
+@node Blocking Factor
+@subsection The Blocking Factor of an Archive
+@cindex Blocking Factor
+@cindex Record Size
+@cindex Number of blocks per record
+@cindex Number of bytes per record
+@cindex Bytes per record
+@cindex Blocks per record
+@UNREVISED
+
+@opindex blocking-factor
+The data in an archive is grouped into blocks, which are 512 bytes.
+Blocks are read and written in whole number multiples called
+@dfn{records}. The number of blocks in a record (ie. the size of a
+record in units of 512 bytes) is called the @dfn{blocking factor}.
+The @option{--blocking-factor=@var{512-size}} (@option{-b
+@var{512-size}}) option specifies the blocking factor of an archive.
+The default blocking factor is typically 20 (i.e., 10240 bytes), but
+can be specified at installation. To find out the blocking factor of
+an existing archive, use @samp{tar --list --file=@var{archive-name}}.
+This may not work on some devices.
+
+Records are separated by gaps, which waste space on the archive media.
+If you are archiving on magnetic tape, using a larger blocking factor
+(and therefore larger records) provides faster throughput and allows you
+to fit more data on a tape (because there are fewer gaps). If you are
+archiving on cartridge, a very large blocking factor (say 126 or more)
+greatly increases performance. A smaller blocking factor, on the other
+hand, may be useful when archiving small files, to avoid archiving lots
+of nulls as @command{tar} fills out the archive to the end of the record.
+In general, the ideal record size depends on the size of the
+inter-record gaps on the tape you are using, and the average size of the
+files you are archiving. @xref{create}, for information on
+writing archives.
+
+@FIXME{Need example of using a cartridge with blocking factor=126 or more.}
+
+Archives with blocking factors larger than 20 cannot be read
+by very old versions of @command{tar}, or by some newer versions
+of @command{tar} running on old machines with small address spaces.
+With @GNUTAR{}, the blocking factor of an archive is limited
+only by the maximum record size of the device containing the archive,
+or by the amount of available virtual memory.
+
+Also, on some systems, not using adequate blocking factors, as sometimes
+imposed by the device drivers, may yield unexpected diagnostics. For
+example, this has been reported:
+
+@smallexample
+Cannot write to /dev/dlt: Invalid argument
+@end smallexample
-@item +add-archive
-Adds copies of an archive or archives to the end of another archive.
+@noindent
+In such cases, it sometimes happen that the @command{tar} bundled by
+the system is aware of block size idiosyncrasies, while @GNUTAR{}
+requires an explicit specification for the block size,
+which it cannot guess. This yields some people to consider
+@GNUTAR{} is misbehaving, because by comparison,
+@cite{the bundle @command{tar} works OK}. Adding @w{@kbd{-b 256}},
+for example, might resolve the problem.
+
+If you use a non-default blocking factor when you create an archive, you
+must specify the same blocking factor when you modify that archive. Some
+archive devices will also require you to specify the blocking factor when
+reading that archive, however this is not typically the case. Usually, you
+can use @option{--list} (@option{-t}) without specifying a blocking factor---@command{tar}
+reports a non-default record size and then lists the archive members as
+it would normally. To extract files from an archive with a non-standard
+blocking factor (particularly if you're not sure what the blocking factor
+is), you can usually use the @option{--read-full-records} (@option{-B}) option while
+specifying a blocking factor larger then the blocking factor of the archive
+(ie. @samp{tar --extract --read-full-records --blocking-factor=300}.
+@xref{list}, for more information on the @option{--list} (@option{-t})
+operation. @xref{Reading}, for a more detailed explanation of that option.
+
+@table @option
+@item --blocking-factor=@var{number}
+@itemx -b @var{number}
+Specifies the blocking factor of an archive. Can be used with any
+operation, but is usually not necessary with @option{--list} (@option{-t}).
+@end table
-@item +add-file
-Adds files to the end of the archive.
+Device blocking
+
+@table @option
+@item -b @var{blocks}
+@itemx --blocking-factor=@var{blocks}
+Set record size to @math{@var{blocks} * 512} bytes.
+
+This option is used to specify a @dfn{blocking factor} for the archive.
+When reading or writing the archive, @command{tar}, will do reads and writes
+of the archive in records of @math{@var{block}*512} bytes. This is true
+even when the archive is compressed. Some devices requires that all
+write operations be a multiple of a certain size, and so, @command{tar}
+pads the archive out to the next record boundary.
+
+The default blocking factor is set when @command{tar} is compiled, and is
+typically 20. Blocking factors larger than 20 cannot be read by very
+old versions of @command{tar}, or by some newer versions of @command{tar}
+running on old machines with small address spaces.
+
+With a magnetic tape, larger records give faster throughput and fit
+more data on a tape (because there are fewer inter-record gaps).
+If the archive is in a disk file or a pipe, you may want to specify
+a smaller blocking factor, since a large one will result in a large
+number of null bytes at the end of the archive.
+
+When writing cartridge or other streaming tapes, a much larger
+blocking factor (say 126 or more) will greatly increase performance.
+However, you must specify the same blocking factor when reading or
+updating the archive.
+
+Apparently, Exabyte drives have a physical block size of 8K bytes.
+If we choose our blocksize as a multiple of 8k bytes, then the problem
+seems to disappear. Id est, we are using block size of 112 right
+now, and we haven't had the problem since we switched@dots{}
+
+With @GNUTAR{} the blocking factor is limited only
+by the maximum record size of the device containing the archive, or by
+the amount of available virtual memory.
+
+However, deblocking or reblocking is virtually avoided in a special
+case which often occurs in practice, but which requires all the
+following conditions to be simultaneously true:
+@itemize @bullet
+@item
+the archive is subject to a compression option,
+@item
+the archive is not handled through standard input or output, nor
+redirected nor piped,
+@item
+the archive is directly handled to a local disk, instead of any special
+device,
+@item
+@option{--blocking-factor} is not explicitly specified on the @command{tar}
+invocation.
+@end itemize
-@item +append
-Adds files to the end of the archive.
+If the output goes directly to a local disk, and not through
+stdout, then the last write is not extended to a full record size.
+Otherwise, reblocking occurs. Here are a few other remarks on this
+topic:
-@item +catenate
-Adds copies of an archive or archives to the end of another archive.
+@itemize @bullet
-@item +compare
-Compares files in the archive with their counterparts in the file
-system, and reports differences in file size, mode, owner,
-modification date and contents.
+@item
+@command{gzip} will complain about trailing garbage if asked to
+uncompress a compressed archive on tape, there is an option to turn
+the message off, but it breaks the regularity of simply having to use
+@samp{@var{prog} -d} for decompression. It would be nice if gzip was
+silently ignoring any number of trailing zeros. I'll ask Jean-loup
+Gailly, by sending a copy of this message to him.
-@item +concatenate
-Adds copies of an archive or archives to the end of another archive.
+@item
+@command{compress} does not show this problem, but as Jean-loup pointed
+out to Michael, @samp{compress -d} silently adds garbage after
+the result of decompression, which tar ignores because it already
+recognized its end-of-file indicator. So this bug may be safely
+ignored.
-@item +create
-Creates a new archive.
+@item
+@samp{gzip -d -q} will be silent about the trailing zeros indeed,
+but will still return an exit status of 2 which tar reports in turn.
+@command{tar} might ignore the exit status returned, but I hate doing
+that, as it weakens the protection @command{tar} offers users against
+other possible problems at decompression time. If @command{gzip} was
+silently skipping trailing zeros @emph{and} also avoiding setting the
+exit status in this innocuous case, that would solve this situation.
-@item +delete
-Deletes files from the archive. All versions of the files are deleted.
+@item
+@command{tar} should become more solid at not stopping to read a pipe at
+the first null block encountered. This inelegantly breaks the pipe.
+@command{tar} should rather drain the pipe out before exiting itself.
+@end itemize
-@item +diff
-Compares files in the archive with their counterparts in the file
-system, and reports differences in file size, mode, owner,
-modification date and contents.
+@opindex ignore-zeros, short description
+@item -i
+@itemx --ignore-zeros
+Ignore blocks of zeros in archive (means EOF).
+
+The @option{--ignore-zeros} (@option{-i}) option causes @command{tar} to ignore blocks
+of zeros in the archive. Normally a block of zeros indicates the
+end of the archive, but when reading a damaged archive, or one which
+was created by concatenating several archives together, this option
+allows @command{tar} to read the entire archive. This option is not on
+by default because many versions of @command{tar} write garbage after
+the zeroed blocks.
+
+Note that this option causes @command{tar} to read to the end of the
+archive file, which may sometimes avoid problems when multiple files
+are stored on a single physical tape.
+
+@opindex read-full-records, short description
+@item -B
+@itemx --read-full-records
+Reblock as we read (for reading 4.2BSD pipes).
+
+If @option{--read-full-records} is used, @command{tar}
+will not panic if an attempt to read a record from the archive does
+not return a full record. Instead, @command{tar} will keep reading
+until it has obtained a full
+record.
+
+This option is turned on by default when @command{tar} is reading
+an archive from standard input, or from a remote machine. This is
+because on BSD Unix systems, a read of a pipe will return however
+much happens to be in the pipe, even if it is less than @command{tar}
+requested. If this option was not used, @command{tar} would fail as
+soon as it read an incomplete record from the pipe.
+
+This option is also useful with the commands for updating an archive.
-@item +extract
-Reads files from the archive and writes them into the active file
-system.
+@end table
-@item +get
-Reads files from the archive and writes them into the active file
-system.
+Tape blocking
+
+@FIXME{Appropriate options should be moved here from elsewhere.}
+
+@cindex blocking factor
+@cindex tape blocking
+
+When handling various tapes or cartridges, you have to take care of
+selecting a proper blocking, that is, the number of disk blocks you
+put together as a single tape block on the tape, without intervening
+tape gaps. A @dfn{tape gap} is a small landing area on the tape
+with no information on it, used for decelerating the tape to a
+full stop, and for later regaining the reading or writing speed.
+When the tape driver starts reading a record, the record has to
+be read whole without stopping, as a tape gap is needed to stop the
+tape motion without loosing information.
+
+@cindex Exabyte blocking
+@cindex DAT blocking
+Using higher blocking (putting more disk blocks per tape block) will use
+the tape more efficiently as there will be less tape gaps. But reading
+such tapes may be more difficult for the system, as more memory will be
+required to receive at once the whole record. Further, if there is a
+reading error on a huge record, this is less likely that the system will
+succeed in recovering the information. So, blocking should not be too
+low, nor it should be too high. @command{tar} uses by default a blocking of
+20 for historical reasons, and it does not really matter when reading or
+writing to disk. Current tape technology would easily accommodate higher
+blockings. Sun recommends a blocking of 126 for Exabytes and 96 for DATs.
+We were told that for some DLT drives, the blocking should be a multiple
+of 4Kb, preferably 64Kb (@w{@kbd{-b 128}}) or 256 for decent performance.
+Other manufacturers may use different recommendations for the same tapes.
+This might also depends of the buffering techniques used inside modern
+tape controllers. Some imposes a minimum blocking, or a maximum blocking.
+Others request blocking to be some exponent of two.
+
+So, there is no fixed rule for blocking. But blocking at read time
+should ideally be the same as blocking used at write time. At one place
+I know, with a wide variety of equipment, they found it best to use a
+blocking of 32 to guarantee that their tapes are fully interchangeable.
+
+I was also told that, for recycled tapes, prior erasure (by the same
+drive unit that will be used to create the archives) sometimes lowers
+the error rates observed at rewriting time.
+
+I might also use @option{--number-blocks} instead of
+@option{--block-number}, so @option{--block} will then expand to
+@option{--blocking-factor} unambiguously.
+
+@node Many
+@section Many Archives on One Tape
+
+@FIXME{Appropriate options should be moved here from elsewhere.}
+
+@findex ntape @r{device}
+Most tape devices have two entries in the @file{/dev} directory, or
+entries that come in pairs, which differ only in the minor number for
+this device. Let's take for example @file{/dev/tape}, which often
+points to the only or usual tape device of a given system. There might
+be a corresponding @file{/dev/nrtape} or @file{/dev/ntape}. The simpler
+name is the @emph{rewinding} version of the device, while the name
+having @samp{nr} in it is the @emph{no rewinding} version of the same
+device.
+
+A rewinding tape device will bring back the tape to its beginning point
+automatically when this device is opened or closed. Since @command{tar}
+opens the archive file before using it and closes it afterwards, this
+means that a simple:
+
+@smallexample
+$ @kbd{tar cf /dev/tape @var{directory}}
+@end smallexample
-@item +help
-Prints a list of @code{tar} operations and options.
+@noindent
+will reposition the tape to its beginning both prior and after saving
+@var{directory} contents to it, thus erasing prior tape contents and
+making it so that any subsequent write operation will destroy what has
+just been saved.
+
+@cindex tape positioning
+So, a rewinding device is normally meant to hold one and only one file.
+If you want to put more than one @command{tar} archive on a given tape, you
+will need to avoid using the rewinding version of the tape device. You
+will also have to pay special attention to tape positioning. Errors in
+positioning may overwrite the valuable data already on your tape. Many
+people, burnt by past experiences, will only use rewinding devices and
+limit themselves to one file per tape, precisely to avoid the risk of
+such errors. Be fully aware that writing at the wrong position on a
+tape loses all information past this point and most probably until the
+end of the tape, and this destroyed information @emph{cannot} be
+recovered.
+
+To save @var{directory-1} as a first archive at the beginning of a
+tape, and leave that tape ready for a second archive, you should use:
+
+@smallexample
+$ @kbd{mt -f /dev/nrtape rewind}
+$ @kbd{tar cf /dev/nrtape @var{directory-1}}
+@end smallexample
+
+@cindex tape marks
+@dfn{Tape marks} are special magnetic patterns written on the tape
+media, which are later recognizable by the reading hardware. These
+marks are used after each file, when there are many on a single tape.
+An empty file (that is to say, two tape marks in a row) signal the
+logical end of the tape, after which no file exist. Usually,
+non-rewinding tape device drivers will react to the close request issued
+by @command{tar} by first writing two tape marks after your archive, and by
+backspacing over one of these. So, if you remove the tape at that time
+from the tape drive, it is properly terminated. But if you write
+another file at the current position, the second tape mark will be
+erased by the new information, leaving only one tape mark between files.
+
+So, you may now save @var{directory-2} as a second archive after the
+first on the same tape by issuing the command:
+
+@smallexample
+$ @kbd{tar cf /dev/nrtape @var{directory-2}}
+@end smallexample
-@item +list
-Prints a list of the contents of the archive.
+@noindent
+and so on for all the archives you want to put on the same tape.
-@item +update
-Adds files to the end of the archive, but only if they are newer than
-their counterparts already in the archive, or if they do not already
-exist in the archive.
+Another usual case is that you do not write all the archives the same
+day, and you need to remove and store the tape between two archive
+sessions. In general, you must remember how many files are already
+saved on your tape. Suppose your tape already has 16 files on it, and
+that you are ready to write the 17th. You have to take care of skipping
+the first 16 tape marks before saving @var{directory-17}, say, by using
+these commands:
-@item +version
-Prints the version number of the @code{tar} program to the standard
-error.
-@end table
+@smallexample
+$ @kbd{mt -f /dev/nrtape rewind}
+$ @kbd{mt -f /dev/nrtape fsf 16}
+$ @kbd{tar cf /dev/nrtape @var{directory-17}}
+@end smallexample
-@node Options, , Operations, Quick Reference
-@appendixsec Table of Options
+In all the previous examples, we put aside blocking considerations, but
+you should do the proper things for that as well. @xref{Blocking}.
-Options change the way @code{tar} performs an operation.
+@menu
+* Tape Positioning:: Tape Positions and Tape Marks
+* mt:: The @command{mt} Utility
+@end menu
-@table @samp
-@item +absolute-paths
-WILL BE INPUT WHEN QUESTION IS RESOLVED
+@node Tape Positioning
+@subsection Tape Positions and Tape Marks
+@UNREVISED
-@item +after-date=@var{date}
-Limit the operation to files changed after the given date.
-@xref{File Exclusion}.
+Just as archives can store more than one file from the file system,
+tapes can store more than one archive file. To keep track of where
+archive files (or any other type of file stored on tape) begin and
+end, tape archive devices write magnetic @dfn{tape marks} on the
+archive media. Tape drives write one tape mark between files,
+two at the end of all the file entries.
-@item +block-size=@var{number}
-Specify the blocking factor of an archive. @xref{Blocking Factor}.
+If you think of data as a series of records "rrrr"'s, and tape marks as
+"*"'s, a tape might look like the following:
-@item +compress
-Specify a compressed archive. @xref{Compressed Archives}.
+@smallexample
+rrrr*rrrrrr*rrrrr*rr*rrrrr**-------------------------
+@end smallexample
-@item +compress-block.
-Create a whole block sized compressed archive. @xref{Compressed Archives}.
+Tape devices read and write tapes using a read/write @dfn{tape
+head}---a physical part of the device which can only access one
+point on the tape at a time. When you use @command{tar} to read or
+write archive data from a tape device, the device will begin reading
+or writing from wherever on the tape the tape head happens to be,
+regardless of which archive or what part of the archive the tape
+head is on. Before writing an archive, you should make sure that no
+data on the tape will be overwritten (unless it is no longer needed).
+Before reading an archive, you should make sure the tape head is at
+the beginning of the archive you want to read. You can do it manually
+via @code{mt} utility (@pxref{mt}). The @code{restore} script does
+that automatically (@pxref{Scripted Restoration}).
-@item +confirmation
-Solicit confirmation for each file. @xref{Interactive Operation}
-<<< +selective should be a synonym.
+If you want to add new archive file entries to a tape, you should
+advance the tape to the end of the existing file entries, backspace
+over the last tape mark, and write the new archive file. If you were
+to add two archives to the example above, the tape might look like the
+following:
-@item +dereference
-Treat a symbolic link as an alternate name for the file the link
-points to. @xref{Symbolic Links}.
+@smallexample
+rrrr*rrrrrr*rrrrr*rr*rrrrr*rrr*rrrr**----------------
+@end smallexample
-@item +directory=@file{directory}
-Change the working directory. @xref{Changing Working Directory}.
+@node mt
+@subsection The @command{mt} Utility
+@UNREVISED
-@item +exclude=@var{pattern}
-Exclude files which match the regular expression @var{pattern}.
-@xref{File Exclusion}.
+@FIXME{Is it true that this only works on non-block devices?
+should explain the difference, (fixed or variable).}
+@xref{Blocking Factor}.
-@item +exclude-from=@file{file}
-Exclude files which match any of the regular expressions listed in
-the file @file{file}. @xref{File Exclusion}.
+You can use the @command{mt} utility to advance or rewind a tape past a
+specified number of archive files on the tape. This will allow you
+to move to the beginning of an archive before extracting or reading
+it, or to the end of all the archives before writing a new one.
+@FIXME{Why isn't there an "advance 'til you find two tape marks
+together"?}
-@item +file=@var{archive-name}
-Name the archive. @xref{Archive Name}).
+The syntax of the @command{mt} command is:
-@item +files-from=@file{file}
-Read file-name arguments from a file on the file system.
-@xref{File Name Lists}.
+@smallexample
+@kbd{mt [-f @var{tapename}] @var{operation} [@var{number}]}
+@end smallexample
-@item +ignore-umask
-Set modes of extracted files to those recorded in the archive.
-@xref{File Writing Options}.
+where @var{tapename} is the name of the tape device, @var{number} is
+the number of times an operation is performed (with a default of one),
+and @var{operation} is one of the following:
-@item +ignore-zeros
-Ignore end-of-archive entries. @xref{Archive Reading Options}.
-<<< this should be changed to +ignore-end
+@FIXME{is there any use for record operations?}
-@item +listed-incremental=@var{file-name} (-g)
-Take a file name argument always. If the file doesn't exist, run a level
-zero dump, creating the file. If the file exists, uses that file to see
-what has changed.
+@table @option
+@item eof
+@itemx weof
+Writes @var{number} tape marks at the current position on the tape.
-@item +incremental (-G)
-@c <<<look it up>>>
+@item fsf
+Moves tape position forward @var{number} files.
-@item +tape-length=@var{n} (-L)
-@c <<<alternate way of doing multi archive, will go to that length and
-@c prompts for new tape, automatically turns on multi-volume. >>>
-@c <<< this needs to be written into main body as well -ringo
+@item bsf
+Moves tape position back @var{number} files.
-@item +info-script=@var{program-file}
-Create a multi-volume archive via a script. @xref{Multi-Volume Archives}.
+@item rewind
+Rewinds the tape. (Ignores @var{number}).
-@item +interactive
-Ask for confirmation before performing any operation on a file or
-archive member.
+@item offline
+@itemx rewoff1
+Rewinds the tape and takes the tape device off-line. (Ignores @var{number}).
-@item +keep-old-files
-Prevent overwriting during extraction. @xref{File Writing Options}.
+@item status
+Prints status information about the tape unit.
-@item +label=@var{archive-label}
-Include an archive-label in the archive being created. @xref{Archive
-Label}.
+@end table
-@item +modification-time
-Set the modification time of extracted files to the time they were
-extracted. @xref{File Writing Options}.
+@FIXME{Is there a better way to frob the spacing on the list?}
-@item +multi-volume
-Specify a multi-volume archive. @xref{Multi-Volume Archives}.
+If you don't specify a @var{tapename}, @command{mt} uses the environment
+variable @env{TAPE}; if @env{TAPE} is not set, @command{mt} uses the device
+@file{/dev/rmt12}.
-@item +newer=@var{date}
-Limit the operation to files changed after the given date.
-@xref{File Exclusion}.
+@command{mt} returns a 0 exit status when the operation(s) were
+successful, 1 if the command was unrecognized, and 2 if an operation
+failed.
-@item +newer-mtime=@var{date}
-Limit the operation to files modified after the given date. @xref{File
-Exclusion}.
+@node Using Multiple Tapes
+@section Using Multiple Tapes
+@UNREVISED
+
+Often you might want to write a large archive, one larger than will fit
+on the actual tape you are using. In such a case, you can run multiple
+@command{tar} commands, but this can be inconvenient, particularly if you
+are using options like @option{--exclude=@var{pattern}} or dumping entire file systems.
+Therefore, @command{tar} supports multiple tapes automatically.
+
+Use @option{--multi-volume} (@option{-M}) on the command line, and
+then @command{tar} will, when it reaches the end of the tape, prompt
+for another tape, and continue the archive. Each tape will have an
+independent archive, and can be read without needing the other. (As
+an exception to this, the file that @command{tar} was archiving when
+it ran out of tape will usually be split between the two archives; in
+this case you need to extract from the first archive, using
+@option{--multi-volume}, and then put in the second tape when
+prompted, so @command{tar} can restore both halves of the file.)
+
+@GNUTAR{} multi-volume archives do not use a truly portable format.
+You need @GNUTAR{} at both ends to process them properly.
+
+When prompting for a new tape, @command{tar} accepts any of the following
+responses:
+
+@table @kbd
+@item ?
+Request @command{tar} to explain possible responses
+@item q
+Request @command{tar} to exit immediately.
+@item n @var{file name}
+Request @command{tar} to write the next volume on the file @var{file name}.
+@item !
+Request @command{tar} to run a subshell. This option can be disabled
+by giving @option{--restrict} command line option to @command{tar}.
+@item y
+Request @command{tar} to begin writing the next volume.
+@end table
-@item +old
-Create an old format archive. @xref{Old Style File Information}.
-@c <<< did we agree this should go away as a synonym?
+(You should only type @samp{y} after you have changed the tape;
+otherwise @command{tar} will write over the volume it just finished.)
+
+@cindex End-of-archive info script
+@cindex Info script
+@anchor{info-script}
+@opindex info-script
+@opindex new-volume-script
+If you want more elaborate behavior than this, give @command{tar} the
+@option{--info-script=@var{script-name}}
+(@option{--new-volume-script=@var{script-name}}, @option{-F
+@var{script-name}}) option. The file @var{script-name} is expected to
+be a program (or shell script) to be run instead of the normal
+prompting procedure. It is executed without any command line
+arguments. Additional data is passed to it via the following
+environment variables:
+
+@table @env
+@vrindex TAR_VERSION, info script environment variable
+@item TAR_VERSION
+@GNUTAR{} version number.
+
+@vrindex TAR_ARCHIVE, info script environment variable
+@item TAR_ARCHIVE
+The name of the archive @command{tar} is processing.
+
+@vrindex TAR_VOLUME, info script environment variable
+@item TAR_VOLUME
+Ordinal number of the volume @command{tar} is about to start.
+
+@vrindex TAR_SUBCOMMAND, info script environment variable
+@item TAR_SUBCOMMAND
+Short option describing the operation @command{tar} is executed.
+@xref{Operations}, for a complete list of subcommand options.
+
+@vrindex TAR_FORMAT, info script environment variable
+@item TAR_FORMAT
+Format of the archive being processed. @xref{Formats}, for a complete
+list of archive format names.
+@end table
-@item +old-archive
-Create an old format archive. @xref{Old Style File Information}.
+The info script can instruct @command{tar} to use new archive name,
+by writing in to file descriptor 3 (see below for an
+example).
+
+If the info script fails, @command{tar} exits; otherwise, it begins
+writing the next volume.
+
+The method @command{tar} uses to detect end of tape is not perfect, and
+fails on some operating systems or on some devices. You can use the
+@option{--tape-length=@var{size}} (@option{-L @var{size}}) option if
+@command{tar} can't detect the end of the tape itself. This option
+selects @option{--multi-volume} (@option{-M}) automatically. The
+@var{size} argument should then be the usable size of the tape in
+units of 1024 bytes. But for many devices, and floppy disks in
+particular, this option is never required for real, as far as we know.
+
+@cindex Volume number file
+@cindex volno file
+@anchor{volno-file}
+@opindex volno-file
+The volume number used by @command{tar} in its tape-change prompt
+can be changed; if you give the
+@option{--volno-file=@var{file-of-number}} option, then
+@var{file-of-number} should be an unexisting file to be created, or
+else, a file already containing a decimal number. That number will be
+used as the volume number of the first volume written. When
+@command{tar} is finished, it will rewrite the file with the
+now-current volume number. (This does not change the volume number
+written on a tape label, as per @ref{label}, it @emph{only} affects
+the number used in the prompt.)
+
+If you want @command{tar} to cycle through a series of files or tape
+drives, there are three approaches to choose from. First of all, you
+can give @command{tar} multiple @option{--file} options. In this case
+the specified files will be used, in sequence, as the successive
+volumes of the archive. Only when the first one in the sequence needs
+to be used again will @command{tar} prompt for a tape change (or run
+the info script). Secondly, you can use the @samp{n} response to the
+tape-change prompt, and, finally, you can use an info script, that
+writes new archive name to file descriptor. The following example
+illustrates this approach:
+
+@smallexample
+@group
+#! /bin/sh
+echo Preparing volume $TAR_VOLUME of $TAR_ARCHIVE.
+
+name=`expr $TAR_ARCHIVE : '\(.*\)-.*'`
+case $TAR_SUBCOMMAND in
+-c) ;;
+-d|-x|-t) test -r $@{name:-$TAR_ARCHIVE@}-$TAR_VOLUME || exit 1
+ ;;
+*) exit 1
+esac
+
+echo $@{name:-$TAR_ARCHIVE@}-$TAR_VOLUME >&3
+@end group
+@end smallexample
+
+Each volume of a multi-volume archive is an independent @command{tar}
+archive, complete in itself. For example, you can list or extract any
+volume alone; just don't specify @option{--multi-volume}
+(@option{-M}). However, if one file in the archive is split across
+volumes, the only way to extract it successfully is with a
+multi-volume extract command @option{--extract --multi-volume}
+(@option{-xM}) starting on or before the volume where the file begins.
+
+For example, let's presume someone has two tape drives on a system
+named @file{/dev/tape0} and @file{/dev/tape1}. For having @GNUTAR{}
+to switch to the second drive when it needs to write the
+second tape, and then back to the first tape, etc., just do either of:
+
+@smallexample
+$ @kbd{tar --create --multi-volume --file=/dev/tape0 --file=/dev/tape1 @var{files}}
+$ @kbd{tar cMff /dev/tape0 /dev/tape1 @var{files}}
+@end smallexample
-@item +one-file-system
-Prevent @code{tar} from crossing file system boundaries when
-archiving. @xref{File Exclusion}.
+@menu
+* Multi-Volume Archives:: Archives Longer than One Tape or Disk
+* Tape Files:: Tape Files
+* Tarcat:: Concatenate Volumes into a Single Archive
-@item +portable
-Create an old format archive. @xref{Old Style File Information}.
-@c <<< was portability, may still need to be changed
+@end menu
-@item +preserve-order
-Help process large lists of file-names on machines with small amounts of
-memory. @xref{Archive Reading Options}.
+@node Multi-Volume Archives
+@subsection Archives Longer than One Tape or Disk
+@cindex Multi-volume archives
+@UNREVISED
-@item +preserve-permission
-Set modes of extracted files to those recorded in the archive.
-@xref{File Writing Options}.
+@opindex multi-volume
+To create an archive that is larger than will fit on a single unit of
+the media, use the @option{--multi-volume} (@option{-M}) option in conjunction with
+the @option{--create} option (@pxref{create}). A @dfn{multi-volume}
+archive can be manipulated like any other archive (provided the
+@option{--multi-volume} option is specified), but is stored on more
+than one tape or disk.
-@item +read-full-blocks
-Read an archive with a smaller than specified block size or which
-contains incomplete blocks. @xref{Archive Reading Options}).
-@c should be +partial-blocks (!!!)
-
-@item +record-number
-Print the record number where a message is generated.
-@xref{Additional Information}.
+When you specify @option{--multi-volume}, @command{tar} does not report an
+error when it comes to the end of an archive volume (when reading), or
+the end of the media (when writing). Instead, it prompts you to load
+a new storage volume. If the archive is on a magnetic tape, you
+should change tapes when you see the prompt; if the archive is on a
+floppy disk, you should change disks; etc.
-@item +same-order
-Help process large lists of file-names on machines with small amounts of
-memory. @xref{Archive Reading Options}.
+You can read each individual volume of a multi-volume archive as if it
+were an archive by itself. For example, to list the contents of one
+volume, use @option{--list}, without @option{--multi-volume} specified.
+To extract an archive member from one volume (assuming it is described
+that volume), use @option{--extract}, again without
+@option{--multi-volume}.
-@item +same-permission
-Set the modes of extracted files to those recorded in the archive.
-@xref{File Writing Options}.
+If an archive member is split across volumes (ie. its entry begins on
+one volume of the media and ends on another), you need to specify
+@option{--multi-volume} to extract it successfully. In this case, you
+should load the volume where the archive member starts, and use
+@samp{tar --extract --multi-volume}---@command{tar} will prompt for later
+volumes as it needs them. @xref{extracting archives}, for more
+information about extracting archives.
-@item +sparse
-Archive sparse files sparsely. @xref{Sparse Files}.
+@option{--info-script=@var{script-name}}
+(@option{--new-volume-script=@var{script-name}}, @option{-F
+@var{script-name}}) (@pxref{info-script}) is like
+@option{--multi-volume} (@option{-M}), except that @command{tar} does
+not prompt you directly to change media volumes when a volume is
+full---instead, @command{tar} runs commands you have stored in
+@var{script-name}. For example, this option can be used to eject
+cassettes, or to broadcast messages such as @samp{Someone please come
+change my tape} when performing unattended backups. When
+@var{script-name} is done, @command{tar} will assume that the media
+has been changed.
-@item +starting-file=@var{file-name}
-Begin reading in the middle of an archive. @xref{Scarce Disk Space}.
+Multi-volume archives can be modified like any other archive. To add
+files to a multi-volume archive, you need to only mount the last
+volume of the archive media (and new volumes, if needed). For all
+other operations, you need to use the entire archive.
-@item +to-stdout
-Write files to the standard output. @xref{File Writing Options}.
+If a multi-volume archive was labeled using
+@option{--label=@var{archive-label}} (@option{-V @var{archive-label}})
+(@pxref{label}) when it was created, @command{tar} will not
+automatically label volumes which are added later. To label
+subsequent volumes, specify @option{--label=@var{archive-label}} again
+in conjunction with the @option{--append}, @option{--update} or
+@option{--concatenate} operation.
-@item +uncompress
-Specifdo a compressed archive. @xref{Compressed Archives}.
+@cindex Labeling multi-volume archives
+@FIXME{example}
-@item -V @var{archive-label}
-Include an archive-label in the archive being created. @xref{Archive
-Label}.
-@c was +volume
+@FIXME{There should be a sample program here, including an exit
+before end. Is the exit status even checked in tar? :-(}
-@item +verbose
-Print the names of files or archive members as they are being
-operated on. @xref{Additional Information}.
+@table @option
+@item --multi-volume
+@itemx -M
+Creates a multi-volume archive, when used in conjunction with
+@option{--create} (@option{-c}). To perform any other operation on a multi-volume
+archive, specify @option{--multi-volume} in conjunction with that
+operation.
-@item +verify
-Check for discrepancies in the archive immediately after it is
-written. @xref{Write Verification}.
+@item --info-script=@var{program-file}
+@itemx --new-volume-script=@var{program-file}
+@itemx -F @var{program-file}
+Creates a multi-volume archive via a script. Used in conjunction with
+@option{--create} (@option{-c}). @xref{info-script}, dor a detailed discussion.
+@end table
-@item -B
-Read an archive with a smaller than specified block size or which
-contains incomplete blocks. @xref{Archive Reading Options}).
+Beware that there is @emph{no} real standard about the proper way, for
+a @command{tar} archive, to span volume boundaries. If you have a
+multi-volume created by some vendor's @command{tar}, there is almost
+no chance you could read all the volumes with @GNUTAR{}.
+The converse is also true: you may not expect
+multi-volume archives created by @GNUTAR{} to be
+fully recovered by vendor's @command{tar}. Since there is little
+chance that, in mixed system configurations, some vendor's
+@command{tar} will work on another vendor's machine, and there is a
+great chance that @GNUTAR{} will work on most of
+them, your best bet is to install @GNUTAR{} on all
+machines between which you know exchange of files is possible.
+
+@node Tape Files
+@subsection Tape Files
+@UNREVISED
+
+To give the archive a name which will be recorded in it, use the
+@option{--label=@var{volume-label}} (@option{-V @var{volume-label}})
+option. This will write a special block identifying
+@var{volume-label} as the name of the archive to the front of the
+archive which will be displayed when the archive is listed with
+@option{--list}. If you are creating a multi-volume archive with
+@option{--multi-volume} (@pxref{Using Multiple Tapes}), then the
+volume label will have @samp{Volume @var{nnn}} appended to the name
+you give, where @var{nnn} is the number of the volume of the archive.
+(If you use the @option{--label=@var{volume-label}}) option when
+reading an archive, it checks to make sure the label on the tape
+matches the one you give. @xref{label}.
+
+When @command{tar} writes an archive to tape, it creates a single
+tape file. If multiple archives are written to the same tape, one
+after the other, they each get written as separate tape files. When
+extracting, it is necessary to position the tape at the right place
+before running @command{tar}. To do this, use the @command{mt} command.
+For more information on the @command{mt} command and on the organization
+of tapes into a sequence of tape files, see @ref{mt}.
+
+People seem to often do:
+
+@smallexample
+@kbd{--label="@var{some-prefix} `date +@var{some-format}`"}
+@end smallexample
+
+or such, for pushing a common date in all volumes or an archive set.
+
+@node Tarcat
+@subsection Concatenate Volumes into a Single Archive
+
+@pindex tarcat
+ Sometimes it is necessary to convert existing @GNUTAR{} multi-volume
+archive to a single @command{tar} archive. Simply concatenating all
+volumes into one will not work, since each volume carries an additional
+information at the beginning. @GNUTAR{} is shipped with the shell
+script @command{tarcat} designed for this purpose.
+
+ The script takes a list of files comprising a multi-volume archive
+and creates the resulting archive at the standard output. For example:
+
+@smallexample
+@kbd{tarcat vol.1 vol.2 vol.3 | tar tf -}
+@end smallexample
+
+ The script implements a simple heuristics to determine the format of
+the first volume file and to decide how to process the rest of the
+files. However, it makes no attempt to verify whether the files are
+given in order or even if they are valid @command{tar} archives.
+It uses @command{dd} and does not filter its standard error, so you
+will usually see lots of spurious messages.
+
+@FIXME{The script is not installed. Should we install it?}
+
+@node label
+@section Including a Label in the Archive
+@cindex Labeling an archive
+@cindex Labels on the archive media
+@UNREVISED
-@item -K @var{file-name}
-Begin reading in the middle of an archive. @xref{Scarce Disk Space}.
+@opindex label
+ To avoid problems caused by misplaced paper labels on the archive
+media, you can include a @dfn{label} entry---an archive member which
+contains the name of the archive---in the archive itself. Use the
+@option{--label=@var{archive-label}} (@option{-V @var{archive-label}})
+option in conjunction with the @option{--create} operation to include
+a label entry in the archive as it is being created.
-@item -M
-Specify a multi-volume archive. @xref{Multi-Volume Archives}.
+@table @option
+@item --label=@var{archive-label}
+@itemx -V @var{archive-label}
+Includes an @dfn{archive-label} at the beginning of the archive when
+the archive is being created, when used in conjunction with the
+@option{--create} operation. Checks to make sure the archive label
+matches the one specified (when used in conjunction with any other
+operation.
+@end table
-@item -N @var{date}
-Limit operation to files changed after the given date. @xref{File Exclusion}.
+ If you create an archive using both
+@option{--label=@var{archive-label}} (@option{-V @var{archive-label}})
+and @option{--multi-volume} (@option{-M}), each volume of the archive
+will have an archive label of the form @samp{@var{archive-label}
+Volume @var{n}}, where @var{n} is 1 for the first volume, 2 for the
+next, and so on. @xref{Using Multiple Tapes}, for information on
+creating multiple volume archives.
+
+@cindex Volume label, listing
+@cindex Listing volume label
+ The volume label will be displayed by @option{--list} along with
+the file contents. If verbose display is requested, it will also be
+explicitely marked as in the example below:
+
+@smallexample
+@group
+$ @kbd{tar --verbose --list --file=iamanarchive}
+V--------- 0 0 0 1992-03-07 12:01 iamalabel--Volume Header--
+-rw-r--r-- ringo user 40 1990-05-21 13:30 iamafilename
+@end group
+@end smallexample
+
+@opindex test-label
+@anchor{--test-label option}
+ However, @option{--list} option will cause listing entire
+contents of the archive, which may be undesirable (for example, if the
+archive is stored on a tape). You can request checking only the volume
+by specifying @option{--test-label} option. This option reads only the
+first block of an archive, so it can be used with slow storage
+devices. For example:
+
+@smallexample
+@group
+$ @kbd{tar --test-label --file=iamanarchive}
+iamalabel
+@end group
+@end smallexample
+
+ If @option{--test-label} is used with a single command line
+argument, @command{tar} compares the volume label with the
+argument. It exits with code 0 if the two strings match, and with code
+2 otherwise. In this case no output is displayed. For example:
+
+@smallexample
+@group
+$ @kbd{tar --test-label --file=iamanarchive 'iamalable'}
+@result{} 0
+$ @kbd{tar --test-label --file=iamanarchive 'iamalable' alabel}
+@result{} 1
+@end group
+@end smallexample
+
+ If you request any operation, other than @option{--create}, along
+with using @option{--label} option, @command{tar} will first check if
+the archive label matches the one specified and will refuse to proceed
+if it does not. Use this as a safety precaution to avoid accidentally
+overwriting existing archives. For example, if you wish to add files
+to @file{archive}, presumably labelled with string @samp{My volume},
+you will get:
+
+@smallexample
+@group
+$ @kbd{tar -rf archive --label 'My volume' .}
+tar: Archive not labeled to match `My volume'
+@end group
+@end smallexample
-@item -O
-Write files to the standard output. @xref{File Writing Options}.
+@noindent
+in case its label does not match. This will work even if
+@file{archive} is not labelled at all.
+
+ Similarly, @command{tar} will refuse to list or extract the
+archive if its label doesn't match the @var{archive-label}
+specified. In those cases, @var{archive-label} argument is interpreted
+as a globbing-style pattern which must match the actual magnetic
+volume label. @xref{exclude}, for a precise description of how match
+is attempted@footnote{Previous versions of @command{tar} used full
+regular expression matching, or before that, only exact string
+matching, instead of wildcard matchers. We decided for the sake of
+simplicity to use a uniform matching device through
+@command{tar}.}. If the switch @option{--multi-volume} (@option{-M}) is being used,
+the volume label matcher will also suffix @var{archive-label} by
+@w{@samp{ Volume [1-9]*}} if the initial match fails, before giving
+up. Since the volume numbering is automatically added in labels at
+creation time, it sounded logical to equally help the user taking care
+of it when the archive is being read.
+
+ The @option{--label} was once called @option{--volume}, but is not
+available under that name anymore.
+
+ You can also use @option{--label} to get a common information on
+all tapes of a series. For having this information different in each
+series created through a single script used on a regular basis, just
+manage to get some date string as part of the label. For example:
+
+@smallexample
+@group
+$ @kbd{tar cfMV /dev/tape "Daily backup for `date +%Y-%m-%d`"}
+$ @kbd{tar --create --file=/dev/tape --multi-volume \
+ --volume="Daily backup for `date +%Y-%m-%d`"}
+@end group
+@end smallexample
+
+ Also note that each label has its own date and time, which corresponds
+to when @GNUTAR{} initially attempted to write it,
+often soon after the operator launches @command{tar} or types the
+carriage return telling that the next tape is ready. Comparing date
+labels does give an idea of tape throughput only if the delays for
+rewinding tapes and the operator switching them were negligible, which
+is usually not the case.
+
+@node verify
+@section Verifying Data as It is Stored
+@cindex Verifying a write operation
+@cindex Double-checking a write operation
-@c <<<<- P is absolute paths, add when resolved. -ringo>>>
+@table @option
+@item -W
+@itemx --verify
+@opindex verify, short description
+Attempt to verify the archive after writing.
+@end table
-@item -R
-Print the record number where a message is generated.
-@xref{Additional Information}.
+This option causes @command{tar} to verify the archive after writing it.
+Each volume is checked after it is written, and any discrepancies
+are recorded on the standard error output.
-@item -S
-Archive sparse files sparsely. @xref{Sparse Files}.
+Verification requires that the archive be on a back-space-able medium.
+This means pipes, some cartridge tape drives, and some other devices
+cannot be verified.
-@item -T @var{file}
-Read file-name arguments from a file on the file system.
-@xref{File Name Lists}.
+You can insure the accuracy of an archive by comparing files in the
+system with archive members. @command{tar} can compare an archive to the
+file system as the archive is being written, to verify a write
+operation, or can compare a previously written archive, to insure that
+it is up to date.
-@item -W
-Check for discrepancies in the archive immediately after it is
-written. @xref{Write Verification}.
+@opindex verify, using with @option{--create}
+@opindex create, using with @option{--verify}
+To check for discrepancies in an archive immediately after it is
+written, use the @option{--verify} (@option{-W}) option in conjunction with
+the @option{--create} operation. When this option is
+specified, @command{tar} checks archive members against their counterparts
+in the file system, and reports discrepancies on the standard error.
-@item -Z
-Specify a compressed archive. @xref{Compressed Archives}.
+To verify an archive, you must be able to read it from before the end
+of the last written entry. This option is useful for detecting data
+errors on some tapes. Archives written to pipes, some cartridge tape
+drives, and some other devices cannot be verified.
-@item -b @var{number}
-Specify the blocking factor of an archive. @xref{Blocking Factor}.
+One can explicitly compare an already made archive with the file
+system by using the @option{--compare} (@option{--diff}, @option{-d})
+option, instead of using the more automatic @option{--verify} option.
+@xref{compare}.
+
+Note that these two options have a slightly different intent. The
+@option{--compare} option checks how identical are the logical contents of some
+archive with what is on your disks, while the @option{--verify} option is
+really for checking if the physical contents agree and if the recording
+media itself is of dependable quality. So, for the @option{--verify}
+operation, @command{tar} tries to defeat all in-memory cache pertaining to
+the archive, while it lets the speed optimization undisturbed for the
+@option{--compare} option. If you nevertheless use @option{--compare} for
+media verification, you may have to defeat the in-memory cache yourself,
+maybe by opening and reclosing the door latch of your recording unit,
+forcing some doubt in your operating system about the fact this is really
+the same volume as the one just written or read.
+
+The @option{--verify} option would not be necessary if drivers were indeed
+able to detect dependably all write failures. This sometimes require many
+magnetic heads, some able to read after the writes occurred. One would
+not say that drivers unable to detect all cases are necessarily flawed,
+as long as programming is concerned.
+
+The @option{--verify} (@option{-W}) option will not work in
+conjunction with the @option{--multi-volume} (@option{-M}) option or
+the @option{--append} (@option{-r}), @option{--update} (@option{-u})
+and @option{--delete} operations. @xref{Operations}, for more
+information on these operations.
+
+Also, since @command{tar} normally strips leading @samp{/} from file
+names (@pxref{absolute}), a command like @samp{tar --verify -cf
+/tmp/foo.tar /etc} will work as desired only if the working directory is
+@file{/}, as @command{tar} uses the archive's relative member names
+(e.g., @file{etc/motd}) when verifying the archive.
+
+@node Write Protection
+@section Write Protection
-@item -f @var{archive-name}
-Name the archive. @xref{Archive Name}).
+Almost all tapes and diskettes, and in a few rare cases, even disks can
+be @dfn{write protected}, to protect data on them from being changed.
+Once an archive is written, you should write protect the media to prevent
+the archive from being accidentally overwritten or deleted. (This will
+protect the archive from being changed with a tape or floppy drive---it
+will not protect it from magnet fields or other physical hazards).
-@item -h
-Treat a symbolic link as an alternate name for the file the link
-points to. @xref{Symbolic Links}.
+The write protection device itself is usually an integral part of the
+physical media, and can be a two position (write enabled/write
+disabled) switch, a notch which can be popped out or covered, a ring
+which can be removed from the center of a tape reel, or some other
+changeable feature.
-@item -i
-Ignore end-of-archive entries. @xref{Archive Reading Options}.
+@node Changes
+@appendix Changes
-@item -k
-Prevent overwriting during extraction. @xref{File Writing Options}.
+This appendix lists some important user-visible changes between
+version @GNUTAR{} @value{VERSION} and previous versions. An up-to-date
+version of this document is available at
+@uref{http://www.gnu.org/@/software/@/tar/manual/changes.html,the
+@GNUTAR{} documentation page}.
-@item -l
-Prevent @code{tar} from crossing file system boundaries when
-archiving. @xref{File Exclusion}.
+@table @asis
+@item Use of short option @option{-o}.
-@item -m
-Set the modification time of extracted files to the time they were
-extracted. @xref{File Writing Options}.
+Earlier versions of @GNUTAR{} understood @option{-o} command line
+option as a synonym for @option{--old-archive}.
-@item -o
-Create an old format archive. @xref{Old Style File Information}.
+@GNUTAR{} starting from version 1.13.90 understands this option as
+a synonym for @option{--no-same-owner}. This is compatible with
+UNIX98 @command{tar} implementations.
-@item -p
-Set the modes of extracted files to those recorded in the archive.
-@xref{File Writing Options}.
+However, to facilitate transition, @option{-o} option retains its
+old semantics when it is used with one of archive-creation commands.
+Users are encouraged to use @option{--format=oldgnu} instead.
-@item -s
-Help process large lists of file-names on machines with small amounts of
-memory. @xref{Archive Reading Options}.
+It is especially important, since versions of @acronym{GNU} Automake
+up to and including 1.8.4 invoke tar with this option to produce
+distribution tarballs. @xref{Formats,v7}, for the detailed discussion
+of this issue and its implications.
-@item -v
-Print the names of files or archive members they are being operated
-on. @xref{Additional Information}.
+Future versions of @GNUTAR{} will understand @option{-o} only as a
+synonym for @option{--no-same-owner}.
-@item -w
-@c <<<see +interactive. WILL BE INPUT WHEN QUESTIONS ARE RESOLVED.>>>
+@item Use of short option @option{-l}
-@item -z
-Specify a compressed archive. @xref{Compressed Archives}.
+Earlier versions of @GNUTAR{} understood @option{-l} option as a
+synonym for @option{--one-file-system}. Such usage is deprecated.
+For compatibility with other implementations future versions of
+@GNUTAR{} will understand this option as a synonym for
+@option{--check-links}.
-@item -z -z
-Create a whole block sized compressed archive. @xref{Compressed Archives}.
-@c I would rather this were -Z. it is the only double letter short
-@c form.
+@item Use of options @option{--portability} and @option{--old-archive}
-@item -C @file{directory}
-Change the working directory. @xref{Changing Working Directory}.
+These options are deprecated. Please use @option{--format=v7} instead.
-@item -F @var{program-file}
-Create a multi-volume archive via a script. @xref{Multi-Volume Archives}.
+@item Use of option @option{--posix}
-@item -X @file{file}
-Exclude files which match any of the regular expressions listed in
-the file @file{file}. @xref{File Exclusion}.
+This option is deprecated. Please use @option{--format=posix} instead.
@end table
-@node Data Format Details, Concept Index, Quick Reference, Top
-@appendix Details of the Archive Data Format
-
-This chapter is based heavily on John Gilmore's @i{tar}(5) manual page
-for the public domain @code{tar} that GNU @code{tar} is based on.
-@c it's been majorly edited since, we may be able to lose this.
+@node Configuring Help Summary
+@appendix Configuring Help Summary
+
+Running @kbd{tar --help} displays the short @command{tar} option
+summary (@pxref{help}). This summary is organised by @dfn{groups} of
+semantically close options. The options within each group are printed
+in the following order: a short option, eventually followed by a list
+of corresponding long option names, followed by a short description of
+the option. For example, here is an excerpt from the actual @kbd{tar
+--help} output:
+
+@verbatim
+ Main operation mode:
+
+ -A, --catenate, --concatenate append tar files to an archive
+ -c, --create create a new archive
+ -d, --diff, --compare find differences between archive and
+ file system
+ --delete delete from the archive
+@end verbatim
+
+@vrindex ARGP_HELP_FMT, environment variable
+The exact visual representation of the help output is configurable via
+@env{ARGP_HELP_FMT} environment variable. The value of this variable
+is a comma-separated list of @dfn{format variable} assignments. There
+are two kinds of format variables. An @dfn{offset variable} keeps the
+offset of some part of help output text from the leftmost column on
+the screen. A @dfn{boolean} variable is a flag that toggles some
+output feature on or off. Depending on the type of the corresponding
+variable, there are two kinds of assignments:
+
+@table @asis
+@item Offset assignment
+
+The assignment to an offset variable has the following syntax:
+
+@smallexample
+@var{variable}=@var{value}
+@end smallexample
-The archive media contains a series of records, each of which contains
-512 bytes. Each archive member is represented by a header record,
-which describes the file, followed by zero or more records which
-represent the contents of the file. At the end of the archive file
-there may be a record consisting of a series of binary zeros, as an
-end-of-archive marker. GNU @code{tar} writes a record of zeros at the
-end of an archive, but does not assume that such a record exists when
-reading an archive.
+@noindent
+where @var{variable} is the variable name, and @var{value} is a
+numeric value to be assigned to the variable.
+
+@item Boolean assignment
+
+To assign @code{true} value to a variable, simply put this variable name. To
+assign @code{false} value, prefix the variable name with @samp{no-}. For
+example:
+
+@smallexample
+@group
+# Assign @code{true} value:
+dup-args
+# Assign @code{false} value:
+no-dup-args
+@end group
+@end smallexample
+@end table
-Records may be grouped into @dfn{blocks} for I/O operations. A block
-of records is written with a single @code{write()} operation. The
-number of records in a block is specified using the @samp{+block-size}
-option. @xref{Blocking Factor}, for more information about specifying
-block size.
+Following variables are declared:
-@menu
-* Header Data:: The Distribution of Data in the Header
-* Header Fields:: The Meaning of Header Fields
-* Sparse File Handling:: Fields to Handle Sparse Files
-@end menu
+@deftypevr {Help Output} boolean dup-args
+If true, arguments for an option are shown with both short and long
+options, even when a given option has both forms, for example:
-@node Header Data, Header Fields, Data Format Details, Data Format Details
-@appendixsec The Distribution of Data in the Header
-
-The header record is defined in C as follows:
-@c I am taking the following code on faith.
-
-@example
-@r{Standard Archive Format - Standard TAR - USTAR}
-
-#define RECORDSIZE 512
-#define NAMSIZ 100
-#define TUNMLEN 32
-#define TGNMLEN 32
-#define SPARSE_EXT_HDR 21
-#define SPARSE_IN_HDR 4
-
-struct sparse @{
- char offset[12];
- char numbytes[12];
-@};
-
-union record @{
- char charptr[RECORDSIZE];
- struct header @{
- char name[NAMSIZ];
- char mode[8];
- char uid[8];
- char gid[8];
- char size[12];
- char mtime[12];
- char chksum[8];
- char linkflag;
- char linkname[NAMSIZ];
- char magic[8];
- char uname[TUNMLEN];
- char gname[TGNMLEN];
- char devmajor[8];
- char devminor[8];
-
-@r{The following fields were added by gnu and are not used by other}
-@r{versions of @code{tar}}.
- char atime[12];
- char ctime[12];
- char offset[12];
- char longnames[4];
-@r{The next three fields were added by gnu to deal with shrinking down}
-@r{sparse files.}
- struct sparse sp[SPARSE_IN_HDR];
- char isextended;
-@r{This is the number of nulls at the end of the file, if any.}
- char ending_blanks[12];
-
- @} header;
-
- struct extended_header @{
- struct sparse sp[21];
- char isextended;
- @} ext_hdr;
-
-@};
-@c <<< this whole thing needs to be put into better english
-
-@r{The checksum field is filled with this while the checksum is computed.}
-#define CHKBLANKS " " @r{8 blanks, no null}
-
-@r{Inclusion of this field marks an archive as being in standard}
-@r{Posix format (though GNU tar itself is not Posix conforming). GNU}
-@r{tar puts "ustar" in this field if uname and gname are valid.}
-#define TMAGIC "ustar " @r{7 chars and a null}
-
-@r{The magic field is filled with this if this is a GNU format dump entry.}
-#define GNUMAGIC "GNUtar " @r{7 chars and a null}
-
-@r{The linkflag defines the type of file.}
-#define LF_OLDNORMAL '\0' @r{Normal disk file, Unix compatible}
-#define LF_NORMAL '0' @r{Normal disk file}
-#define LF_LINK '1' @r{Link to previously dumped file}
-#define LF_SYMLINK '2' @r{Symbolic link}
-#define LF_CHR '3' @r{Character special file}
-#define LF_BLK '4' @r{Block special file}
-#define LF_DIR '5' @r{Directory}
-#define LF_FIFO '6' @r{FIFO special file}
-#define LF_CONTIG '7' @r{Contiguous file}
-
-@r{hhe following are further link types which were defined later.}
-
-@r{This is a dir entry that contains the names of files that were in}
-@r{the dir at the time the dump was made.}
-#define LF_DUMPDIR 'D'
-
-@r{This is the continuation of a file that began on another volume}
-#define LF_MULTIVOL 'M'
-
-@r{This is for sparse files}
-#define LF_SPARSE 'S'
-
-@r{This file is a tape/volume header. Ignore it on extraction.}
-#define LF_VOLHDR 'V'
-
-@r{These are bits used in the mode field - the values are in octal}
-#define TSUID 04000 @r{Set UID on execution}
-#define TSGID 02000 @r{Set GID on execution}
-#define TSVTX 01000 @r{Save text (sticky bit)}
-
-@r{These are file permissions}
-#define TUREAD 00400 @r{read by owner}
-#define TUWRITE 00200 @r{write by owner}
-#define TUEXEC 00100 @r{execute/search by owner}
-#define TGREAD 00040 @r{read by group}
-#define TGWRITE 00020 @r{write by group}
-#define TGEXEC 00010 @r{execute/search by group}
-#define TOREAD 00004 @r{read by other}
-#define TOWRITE 00002 @r{write by other}
-#define TOEXEC 00001 @r{execute/search by other}
-@end example
-
-
-All characters in headers are 8-bit characters in the local variant of
-ASCII. Each field in the header is contiguous; that is, there is no
-padding in the header format.
-
-Data representing the contents of files is not translated in any way
-and is not constrained to represent characters in any character set.
-@code{tar} does not distinguish between text files and binary files.
+@smallexample
+ -f ARCHIVE, --file=ARCHIVE use archive file or device ARCHIVE
+@end smallexample
-The @code{name}, @code{linkname}, @code{magic}, @code{uname}, and
-@code{gname} fields contain null-terminated character strings. All
-other fields contain zero-filled octal numbers in ASCII. Each numeric
-field of width @var{w} contains @var{w} @minus{} 2 digits, a space, and a
-null, except @code{size} and @code{mtime}, which do not contain the
-trailing null.
-
-@node Header Fields, Sparse File Handling, Header Data, Data Format Details
-@appendixsec The Meaning of Header Fields
-
-The @code{name} field contains the name of the file.
-<<< how big a name before field overflows?
-
-The @code{mode} field contains nine bits which specify file
-permissions, and three bits which specify the Set UID, Set GID, and
-Save Text (``stick'') modes. Values for these bits are defined above.
-@xref{File Writing Options}, for information on how file permissions
-and modes are used by @code{tar}.
-
-The @code{uid} and @code{gid} fields contain the numeric user and
-group IDs of the file owners. If the operating system does not
-support numeric user or group IDs, these fields should be ignored.
-@c but are they?
-
-The @code{size} field contains the size of the file in bytes; this
-field contains a zero if the header describes a link to a file.
-
-The @code{mtime} field contains the modification time of the file.
-This is the ASCII representation of the octal value of the last time
-the file was modified, represented as an integer number of seconds
-since January 1, 1970, 00:00 Coordinated Universal Time.
-@xref{File Writing Options}, for a description of how @code{tar} uses
-this information.
-
-The @code{chksum} field contains the ASCII representation of the octal
-value of the simple sum of all bytes in the header record. To
-generate this sum, each 8-bit byte in the header is added to an
-unsigned integer, which has been initialized to zero. The precision
-of the integer is seventeen bits. When calculating the checksum, the
-@code{chksum} field itself is treated as blank.
-
-The @code{atime} and @code{ctime} fields are used when making
-incremental backups; they store, respectively, the file's access time
-and last inode-change time.
-
-The value in the @code{offset} field is used when making a
-multi-volume archive. The offset is number of bytes into the file
-that we need to go to pick up where we left off in the previous
-volume, i.e the location that a continued file is continued from.
-
-The @code{longnames} field supports a feature that is not yet
-implemented. This field should be empty.
-
-The @code{magic} field indicates that this archive was output in the
-P1003 archive format. If this field contains @code{TMAGIC}, the
-@code{uname} and @code{gname} fields will contain the ASCII
-representation of the owner and group of the file respectively. If
-found, the user and group IDs are used rather than the values in the
-@code{uid} and @code{gid} fields.
-
-The @code{sp} field is used to archive sparse files efficiently.
-@xref{Sparse File Handling}, for a description of this field, and
-other fields it may imply.
-
-The @code{typeflag} field specifies the file's type. If a particular
-implementation does not recognize or permit the specified type,
-@code{tar} extracts the file as if it were a regular file, and reports
-the discrepancy on the standard error. @xref{File Types}. @xref{GNU
-File Types}.
+If false, then if an option has both short and long forms, the
+argument is only shown with the long one, for example:
-@menu
-* File Types:: File Types
-* GNU File Types:: Additional File Types Supported by GNU
-@end menu
+@smallexample
+ -f, --file=ARCHIVE use archive file or device ARCHIVE
+@end smallexample
-@node File Types, GNU File Types, Header Fields, Header Fields
-@appendixsubsec File Types
+@noindent
+and a message indicating that the argument is applicable to both
+forms is printed below the options. This message can be disabled
+using @code{dup-args-note} (see below).
-The following flags are used to describe file types:
+The default is false.
+@end deftypevr
-@table @code
-@item LF_NORMAL
-@itemx LF_OLDNORMAL
-Indicates a regular file. In order to be compatible with older
-versions of @code{tar}, a @code{typeflag} value of @code{LF_OLDNORMAL}
-should be silently recognized as a regular file. New archives should
-be created using @code{LF_NORMAL} for regular files. For backward
-compatibility, @code{tar} treats a regular file whose name ends with a
-slash as a directory.
-
-@item LF_LINK
-Indicates a link to another file, of any type, which has been
-previously archived. @code{tar} identifies linked files in Unix by
-matching device and inode numbers. The linked-to name is specified in
-the @code{linkname} field with a trailing null.
-
-@item LF_SYMLINK
-Indicates a symbolic link to another file. The linked-to
-name is specified in the @code{linkname} field with a trailing null.
-@xref{File Writing Options}, for information on archiving files
-referenced by a symbolic link.
-
-@item LF_CHR
-@itemx LF_BLK
-Indicate character special files and block special files,
-respectively. In this case the @code{devmajor} and @code{devminor}
-fields will contain the major and minor device numbers. Operating
-systems may map the device specifications to their own local
-specification, or may ignore the entry.
-
-@item LF_DIR
-Indicates a directory or sub-directory. The directory name in the
-@code{name} field should end with a slash. On systems where disk
-allocation is performed on a directory basis, the @code{size} field
-will contain the maximum number of bytes (which may be rounded to the
-nearest disk block allocation unit) that the directory can hold. A
-@code{size} field of zero indicates no size limitations. Systems that
-do not support size limiting in this manner should ignore the
-@code{size} field.
+@deftypevr {Help Output} boolean dup-args-note
+If this variable is true, which is the default, the following notice
+is displayed at the end of the help output:
-@item LF_FIFO
-Indicates a FIFO special file. Note that archiving a FIFO file
-archives the existence of the file and not its contents.
+@quotation
+Mandatory or optional arguments to long options are also mandatory or
+optional for any corresponding short options.
+@end quotation
-@item LF_CONTIG
-Indicates a contiguous file. Contiguous files are the same as normal
-files except that, in operating systems that support it, all the
-files' disk space is allocated contiguously. Operating systems which
-do not allow contiguous allocation should silently treat this type as
-a normal file.
+Setting @code{no-dup-args-note} inhibits this message. Normally, only one of
+variables @code{dup-args} or @code{dup-args-note} should be set.
+@end deftypevr
+
+@deftypevr {Help Output} offset short-opt-col
+Column in which short options start. Default is 2.
+
+@smallexample
+@group
+$ @kbd{tar --help|grep ARCHIVE}
+ -f, --file=ARCHIVE use archive file or device ARCHIVE
+$ @kbd{ARGP_HELP_FMT=short-opt-col=6 tar --help|grep ARCHIVE}
+ -f, --file=ARCHIVE use archive file or device ARCHIVE
+@end group
+@end smallexample
+@end deftypevr
+
+@deftypevr {Help Output} offset long-opt-col
+Column in which long options start. Default is 6. For example:
+
+@smallexample
+@group
+$ @kbd{tar --help|grep ARCHIVE}
+ -f, --file=ARCHIVE use archive file or device ARCHIVE
+$ @kbd{ARGP_HELP_FMT=long-opt-col=16 tar --help|grep ARCHIVE}
+ -f, --file=ARCHIVE use archive file or device ARCHIVE
+@end group
+@end smallexample
+@end deftypevr
+
+@deftypevr {Help Output} offset doc-opt-col
+Column in which @dfn{doc options} start. A doc option isn't actually
+an option, but rather an arbitrary piece of documentation that is
+displayed in much the same manner as the options. For example, in
+the description of @option{--format} option:
+
+@smallexample
+@group
+ -H, --format=FORMAT create archive of the given format.
+
+ FORMAT is one of the following:
+
+ gnu GNU tar 1.13.x format
+ oldgnu GNU format as per tar <= 1.12
+ pax POSIX 1003.1-2001 (pax) format
+ posix same as pax
+ ustar POSIX 1003.1-1988 (ustar) format
+ v7 old V7 tar format
+@end group
+@end smallexample
-@item 'A' @dots{}
-@itemx 'Z'
-These are reserved for custom implementations. Some of these are used
-in the GNU modified format, which is described below. @xref{GNU File
-Types}.
-@end table
+@noindent
+the format names are doc options. Thus, if you set
+@kbd{ARGP_HELP_FMT=doc-opt-col=6} the above part of the help output
+will look as follows:
+
+@smallexample
+@group
+ -H, --format=FORMAT create archive of the given format.
+
+ FORMAT is one of the following:
+
+ gnu GNU tar 1.13.x format
+ oldgnu GNU format as per tar <= 1.12
+ pax POSIX 1003.1-2001 (pax) format
+ posix same as pax
+ ustar POSIX 1003.1-1988 (ustar) format
+ v7 old V7 tar format
+@end group
+@end smallexample
+@end deftypevr
+
+@deftypevr {Help Output} offset opt-doc-col
+Column in which option description starts. Default is 29.
+
+@smallexample
+@group
+$ @kbd{tar --help|grep ARCHIVE}
+ -f, --file=ARCHIVE use archive file or device ARCHIVE
+$ @kbd{ARGP_HELP_FMT=opt-doc-col=19 tar --help|grep ARCHIVE}
+ -f, --file=ARCHIVE use archive file or device ARCHIVE
+$ @kbd{ARGP_HELP_FMT=opt-doc-col=9 tar --help|grep ARCHIVE}
+ -f, --file=ARCHIVE
+ use archive file or device ARCHIVE
+@end group
+@end smallexample
-Certain other flag values are reserved for specification in future
-revisions of the P1003 standard, and should not be used by any
-@code{tar} program.
+@noindent
+Notice, that the description starts on a separate line if
+@code{opt-doc-col} value is too small.
+@end deftypevr
+
+@deftypevr {Help Output} offset header-col
+Column in which @dfn{group headers} are printed. A group header is a
+descriptive text preceding an option group. For example, in the
+following text:
+
+@verbatim
+ Main operation mode:
+
+ -A, --catenate, --concatenate append tar files to
+ an archive
+ -c, --create create a new archive
+@end verbatim
+@noindent
+@samp{Main operation mode:} is the group header.
-@node GNU File Types, , File Types, Header Fields
-@appendixsubsec Additional File Types Supported by GNU
+The default value is 1.
+@end deftypevr
-GNU @code{tar} uses additional file types to describe new types of
-files in an archive. These are listed below.
+@deftypevr {Help Output} offset usage-indent
+Indentation of wrapped usage lines. Affects @option{--usage}
+output. Default is 12.
+@end deftypevr
-@table @code
-@item LF_DUMPDIR
-@itemx 'D'
-Indicates a directory and a list of files created by the
-@samp{+incremental} option. The @code{size} field gives the total
-size of the associated list of files. Each file name is preceded by
-either a @code{'Y'} (the file should be in this archive) or an
-@code{'N'} (the file is a directory, or is not stored in the archive).
-Each file name is terminated by a null. There is an additional null
-after the last file name.
+@deftypevr {Help Output} offset rmargin
+Right margin of the text output. Used for wrapping.
+@end deftypevr
-@item LF_MULTIVOL
-@itemx 'M'
-Indicates a file continued from another volume of a multi-volume
-archive (@pxref{Multi-Volume Archives}). The original type of the file is not
-given here. The @code{size} field gives the maximum size of this
-piece of the file (assuming the volume does not end before the file is
-written out). The @code{offset} field gives the offset from the
-beginning of the file where this part of the file begins. Thus
-@code{size} plus @code{offset} should equal the original size of the
-file.
+@node Genfile
+@appendix Genfile
+@include genfile.texi
-@item LF_SPARSE
-@itemx 'S'
-Indicates a sparse file. @xref{Sparse Files}. @xref{Sparse File
-Handling}.
+@node Snapshot Files
+@appendix Format of the Incremental Snapshot Files
+@include snapshot.texi
-@item LF_VOLHDR
-@itemx 'V'
-Marks an archive label that was created using the @samp{+label} option
-when the archive was created (@pxref{Archive Label}. The @code{name}
-field contains the argument to the option. The @code{size} field is
-zero. Only the first file in each volume of an archive should have
-this type.
-@end table
+@node Free Software Needs Free Documentation
+@appendix Free Software Needs Free Documentation
+@include freemanuals.texi
-@node Sparse File Handling, , Header Fields, Data Format Details
-@appendixsec Fields to Handle Sparse Files
+@node Copying This Manual
+@appendix Copying This Manual
-The following header information was added to deal with sparse files
-(@pxref{Sparse Files}):
+@menu
+* GNU Free Documentation License:: License for copying this manual
+@end menu
-@c TALK TO MIB
-The @code{sp} field (fields? something else?) is an array of
-@code{struct sparse}. Each @code{struct sparse} contains two
-12-character strings, which represent the offset into the file and the
-number of bytes to be written at that offset. The offset is absolute,
-and not relative to the offset in preceding array elements.
+@include fdl.texi
-The header can contain four of these @code{struct sparse}; if more are
-needed, they are not stored in the header, instead, the flag
-@code{isextended} is set and the next record is an
-@code{extended_header}.
-@c @code{extended_header} or @dfn{extended_header} ??? the next
-@c record after the header, or in the middle of it.
+@node Index of Command Line Options
+@appendix Index of Command Line Options
-The @code{isextended} flag is only set for sparse files, and then only
-if extended header records are needed when archiving the file.
+This appendix contains an index of all @GNUTAR{} long command line
+options. The options are listed without the preceeding double-dash.
-Each extended header record can contain an array of 21 sparse
-structures, as well as another @code{isextended} flag. There is no
-limit (except that implied by the archive media) on the number of
-extended header records that can be used to describe a sparse file.
+@FIXME{@itemize
+@item Make sure @emph{all} options are indexed.
+@item Provide an index of short options
+@end itemize}
-@c so is @code{extended_header} the right way to write this?
+@printindex op
-@node Concept Index, , Data Format Details, Top
-@unnumbered Concept Index
+@node Index
+@appendix Index
@printindex cp
@contents
@bye
-
+@c Local variables:
+@c texinfo-column-for-description: 32
+@c End:
projects / chaz / tar / blobdiff