+++ /dev/null
-\input texinfo @c -*-texinfo-*-
-@comment %**start of header
-@setfilename tar.info
-@include version.texi
-@settitle GNU tar @value{VERSION}
-@setchapternewpage odd
-
-@finalout
-
-@smallbook
-@c %**end of header
-
-@c Maintenance notes:
-@c 1. Pay attention to @FIXME{}s and @UNREVISED{}s
-@c 2. Before creating final variant:
-@c 2.1. Run `make check-options' to make sure all options are properly
-@c documented;
-@c 2.2. Run `make master-menu' (see comment before the master menu).
-
-@include rendition.texi
-@include value.texi
-
-@defcodeindex op
-
-@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
-
-@copying
-
-This manual is for @acronym{GNU} @command{tar} (version
-@value{VERSION}, @value{UPDATED}), which creates and extracts files
-from archives.
-
-Copyright @copyright{} 1992, 1994, 1995, 1996, 1997, 1999, 2000, 2001,
-2003, 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc.
-
-@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 no
-Invariant Sections, 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 have the freedom to
-copy and modify this GNU manual. Buying copies from the FSF
-supports it in developing GNU and promoting software freedom.''
-@end quotation
-@end copying
-
-@dircategory Archiving
-@direntry
-* Tar: (tar). Making tape (or disk) archives.
-@end direntry
-
-@dircategory Individual utilities
-@direntry
-* tar: (tar)tar invocation. Invoking @GNUTAR{}.
-@end direntry
-
-@shorttitlepage @acronym{GNU} @command{tar}
-
-@titlepage
-@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
-@insertcopying
-@end titlepage
-
-@ifnottex
-@node Top
-@top @acronym{GNU} tar: an archiver tool
-
-@insertcopying
-
-@cindex file archival
-@cindex archiving files
-
-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
-
-@c The master menu goes here.
-@c
-@c NOTE: To update it from within Emacs, make sure mastermenu.el is
-@c loaded and run texinfo-master-menu.
-@c To update it from the command line, run
-@c
-@c make master-menu
-
-@menu
-* Introduction::
-* Tutorial::
-* tar invocation::
-* operations::
-* Backups::
-* Choosing::
-* Date input formats::
-* Formats::
-* Media::
-
-Appendices
-
-* Changes::
-* Configuring Help Summary::
-* Fixing Snapshot Files::
-* Tar Internals::
-* Genfile::
-* Free Software Needs Free Documentation::
-* Copying This Manual::
-* Index of Command Line Options::
-* Index::
-
-@detailmenu
- --- The Detailed Node Listing ---
-
-Introduction
-
-* 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
-
-Tutorial Introduction to @command{tar}
-
-* 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::
-
-Two Frequently Used Options
-
-* file tutorial::
-* verbose tutorial::
-* help tutorial::
-
-How to Create Archives
-
-* prepare for examples::
-* Creating the archive::
-* create verbose::
-* short create::
-* create dir::
-
-How to List Archives
-
-* list dir::
-
-How to Extract Members from an Archive
-
-* extracting archives::
-* extracting files::
-* extract dir::
-* extracting untrusted archives::
-* failing commands::
-
-Invoking @GNUTAR{}
-
-* Synopsis::
-* using tar options::
-* Styles::
-* All Options::
-* help::
-* defaults::
-* verbose::
-* checkpoints::
-* interactive::
-
-The Three Option Styles
-
-* Long Options:: Long Option Style
-* Short Options:: Short Option Style
-* Old Options:: Old Option Style
-* Mixing:: Mixing Option Styles
-
-All @command{tar} Options
-
-* Operation Summary::
-* Option Summary::
-* Short Option Summary::
-
-@GNUTAR{} Operations
-
-* Basic tar::
-* Advanced tar::
-* create options::
-* extract options::
-* backup::
-* Applications::
-* looking ahead::
-
-Advanced @GNUTAR{} Operations
-
-* Operations::
-* append::
-* update::
-* concatenate::
-* delete::
-* compare::
-
-How to Add Files to Existing Archives: @option{--append}
-
-* appending files:: Appending Files to an Archive
-* multiple::
-
-Updating an Archive
-
-* how to update::
-
-Options Used by @option{--create}
-
-* override:: Overriding File Metadata.
-* Ignore Failed Read::
-
-Options Used by @option{--extract}
-
-* Reading:: Options to Help Read Archives
-* Writing:: Changing How @command{tar} Writes Files
-* Scarce:: Coping with Scarce Resources
-
-Options to Help Read Archives
-
-* read full records::
-* Ignore Zeros::
-
-Changing How @command{tar} Writes Files
-
-* 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::
-
-Coping with Scarce Resources
-
-* Starting File::
-* Same Order::
-
-Performing Backups and Restoring Files
-
-* 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
-
-Setting Parameters for Backups and Restoration
-
-* General-Purpose Variables::
-* Magnetic Tape Control::
-* User Hooks::
-* backup-specs example:: An Example Text of @file{Backup-specs}
-
-Choosing Files and Names for @command{tar}
-
-* file:: Choosing the Archive's Name
-* Selecting Archive Members::
-* files:: Reading Names from a File
-* exclude:: Excluding Some Files
-* wildcards:: Wildcards Patterns and Matching
-* quoting styles:: Ways of Quoting Special Characters in Names
-* transform:: Modifying File and Member Names
-* after:: Operating Only on New Files
-* recurse:: Descending into Directories
-* one:: Crossing File System Boundaries
-
-Reading Names from a File
-
-* nul::
-
-Excluding Some Files
-
-* problems with exclude::
-
-Wildcards Patterns and Matching
-
-* controlling pattern-matching::
-
-Crossing File System Boundaries
-
-* directory:: Changing Directory
-* absolute:: Absolute File Names
-
-Date input formats
-
-* 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.
-* Specifying time zone rules:: TZ="America/New_York", TZ="UTC0".
-* Authors of get_date:: Bellovin, Eggert, Salz, Berets, et al.
-
-Controlling the Archive Format
-
-* Compression:: Using Less Space through Compression
-* Attributes:: Handling File Attributes
-* Portability:: Making @command{tar} Archives More Portable
-* cpio:: Comparison of @command{tar} and @command{cpio}
-
-Using Less Space through Compression
-
-* gzip:: Creating and Reading Compressed Archives
-* sparse:: Archiving Sparse Files
-
-Making @command{tar} Archives More Portable
-
-* Portable Names:: Portable Names
-* dereference:: Symbolic Links
-* hard links:: Hard 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.
-* Other Tars:: How to Extract GNU-Specific Data Using
- Other @command{tar} Implementations
-
-@GNUTAR{} and @acronym{POSIX} @command{tar}
-
-* PAX keywords:: Controlling Extended Header Keywords.
-
-How to Extract GNU-Specific Data Using Other @command{tar} Implementations
-
-* Split Recovery:: Members Split Between Volumes
-* Sparse Recovery:: Sparse Members
-
-Tapes and Other Archive Media
-
-* 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::
-
-Blocking
-
-* Format Variations:: Format Variations
-* Blocking Factor:: The Blocking Factor of an Archive
-
-Many Archives on One Tape
-
-* Tape Positioning:: Tape Positions and Tape Marks
-* mt:: The @command{mt} Utility
-
-Using Multiple Tapes
-
-* Multi-Volume Archives:: Archives Longer than One Tape or Disk
-* Tape Files:: Tape Files
-* Tarcat:: Concatenate Volumes into a Single Archive
-
-
-Tar Internals
-
-* Standard:: Basic Tar Format
-* Extensions:: @acronym{GNU} Extensions to the Archive Format
-* Sparse Formats:: Storing Sparse Files
-* Snapshot Files::
-* Dumpdir::
-
-Storing Sparse Files
-
-* Old GNU Format::
-* PAX 0:: PAX Format, Versions 0.0 and 0.1
-* PAX 1:: PAX Format, Version 1.0
-
-Genfile
-
-* Generate Mode:: File Generation Mode.
-* Status Mode:: File Status Mode.
-* Exec Mode:: Synchronous Execution mode.
-
-Copying This Manual
-
-* GNU Free Documentation License:: License for copying this manual
-
-@end detailmenu
-@end menu
-
-@node Introduction
-@chapter Introduction
-
-@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.
-
-@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
-
-@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.
-
-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.
-
-@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).
-
-You can use @command{tar} archives in many ways. We want to stress a few
-of them: storage, backup, and transportation.
-
-@FIXME{the following table entries need a bit of work.}
-@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 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. The book for versions from 1.14 up to @value{VERSION} were edited
-by the current maintainer, Sergey Poznyakoff.
-
-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.
-
-@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
-
-@node assumptions
-@section Assumptions this Tutorial Makes
-
-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
-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 @samp{argument} mean, and the
-differences between relative and absolute file names. @FIXME{and what
-else?}
-
-@item
-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 file names,
-we will assume that those names are relative to your home directory.
-For example, my home directory is @file{/home/fsf/melissa}. All of
-my examples are in a subdirectory of the directory named by that file
-name; the subdirectory is called @file{practice}.
-
-@item
-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
-
-@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. 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{Long 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
-
-@noindent
-you can type
-@smallexample
-@kbd{tar -c -v -f afiles.tar apple angst aspic}
-@end smallexample
-
-@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
-* file tutorial::
-* verbose tutorial::
-* help tutorial::
-@end menu
-
-@node file tutorial
-@unnumberedsubsec The @option{--file} Option
-
-@table @option
-@xopindex{file, tutorial}
-@item --file=@var{archive-name}
-@itemx -f @var{archive-name}
-Specify the name of an archive file.
-@end table
-
-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
-
-@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}.
-
-@node verbose tutorial
-@unnumberedsubsec The @option{--verbose} Option
-
-@table @option
-@xopindex{verbose, introduced}
-@item --verbose
-@itemx -v
-Show the files being worked on as @command{tar} is running.
-@end table
-
-@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.
-
-Each instance of @option{--verbose} on the command line increases the
-verbosity level by one, so if you need more details on the output,
-specify it twice.
-
-When reading archives (@option{--list}, @option{--extract},
-@option{--diff}), @command{tar} by default prints only the names of
-the members being extracted. Using @option{--verbose} will show a full,
-@command{ls} style member listing.
-
-In contrast, when writing archives (@option{--create}, @option{--append},
-@option{--update}), @command{tar} does not print file names by
-default. So, a single @option{--verbose} option shows the file names
-being added to the archive, while two @option{--verbose} options
-enable the full listing.
-
-For example, to create an archive in verbose mode:
-
-@smallexample
-$ @kbd{tar -cvf afiles.tar apple angst aspic}
-apple
-angst
-aspic
-@end smallexample
-
-@noindent
-Creating the same archive with the verbosity level 2 could give:
-
-@smallexample
-$ @kbd{tar -cvvf afiles.tar apple angst aspic}
--rw-r--r-- gray/staff 62373 2006-06-09 12:06 apple
--rw-r--r-- gray/staff 11481 2006-06-09 12:06 angst
--rw-r--r-- gray/staff 23152 2006-06-09 12:06 aspic
-@end smallexample
-
-@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:
-
-@smallexample
-$ @kbd{tar --create --verbose --verbose @dots{}}
-@end smallexample
-
-@noindent
-Note that you must double the hyphens properly each time.
-
-Later in the tutorial, we will give examples using @w{@option{--verbose
---verbose}}.
-
-@anchor{verbose member listing}
-The full output consists of six fields:
-
-@itemize @bullet
-@item File type and permissions in symbolic form.
-These are displayed in the same format as the first column of
-@command{ls -l} output (@pxref{What information is listed,
-format=verbose, Verbose listing, fileutils, GNU file utilities}).
-
-@item Owner name and group separated by a slash character.
-If these data are not available (for example, when listing a @samp{v7} format
-archive), numeric @acronym{ID} values are printed instead.
-
-@item Size of the file, in bytes.
-
-@item File modification date in ISO 8601 format.
-
-@item File modification time.
-
-@item File name.
-If the name contains any special characters (white space, newlines,
-etc.) these are displayed in an unambiguous form using so called
-@dfn{quoting style}. For the detailed discussion of available styles
-and on how to use them, see @ref{quoting styles}.
-
-Depending on the file type, the name can be followed by some
-additional information, described in the following table:
-
-@table @samp
-@item -> @var{link-name}
-The file or archive member is a @dfn{symbolic link} and
-@var{link-name} is the name of file it links to.
-
-@item link to @var{link-name}
-The file or archive member is a @dfn{hard link} and @var{link-name} is
-the name of file it links to.
-
-@item --Long Link--
-The archive member is an old GNU format long link. You will normally
-not encounter this.
-
-@item --Long Name--
-The archive member is an old GNU format long name. You will normally
-not encounter this.
-
-@item --Volume Header--
-The archive member is a GNU @dfn{volume header} (@pxref{Tape Files}).
-
-@item --Continued at byte @var{n}--
-Encountered only at the beginning of a multi-volume archive
-(@pxref{Using Multiple Tapes}). This archive member is a continuation
-from the previous volume. The number @var{n} gives the offset where
-the original file was split.
-
-@item unknown file type @var{c}
-An archive member of unknown type. @var{c} is the type character from
-the archive header. If you encounter such a message, it means that
-either your archive contains proprietary member types @GNUTAR{} is not
-able to handle, or the archive is corrupted.
-@end table
-
-@end itemize
-
-For example, here is an archive listing containing most of the special
-suffixes explained above:
-
-@smallexample
-@group
-V--------- 0/0 1536 2006-06-09 13:07 MyVolume--Volume Header--
--rw-r--r-- gray/staff 456783 2006-06-09 12:06 aspic--Continued at
-byte 32456--
--rw-r--r-- gray/staff 62373 2006-06-09 12:06 apple
-lrwxrwxrwx gray/staff 0 2006-06-09 13:01 angst -> apple
--rw-r--r-- gray/staff 35793 2006-06-09 12:06 blues
-hrw-r--r-- gray/staff 0 2006-06-09 12:06 music link to blues
-@end group
-@end smallexample
-
-@smallexample
-@end smallexample
-
-@node help tutorial
-@unnumberedsubsec Getting Help: Using the @option{--help} Option
-
-@table @option
-@opindex help
-@item --help
-
-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
-
-@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.
-
-@menu
-* prepare for examples::
-* Creating the archive::
-* create verbose::
-* short create::
-* create dir::
-@end menu
-
-@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 file 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
-
-@xopindex{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
-
-@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 sequence
-@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.
-@xref{Choosing}, for the detailed discussion on these.) 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
-Creating the archive @samp{collection.tar} did not destroy the copies of
-the files in the directory.
-
-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.
-
-@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}.
-
-@node create verbose
-@subsection Running @option{--create} with @option{--verbose}
-
-@xopindex{create, using with @option{--verbose}}
-@xopindex{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:
-
-@smallexample
-$ @kbd{tar --create --verbose --file=collection.tar blues folk jazz}
-blues
-folk
-jazz
-@end smallexample
-
-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
-
-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.
-
-@node short create
-@subsection Short Forms with @samp{create}
-
-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:
-
-@smallexample
-$ @kbd{tar -cvf collection.tar blues folk jazz}
-blues
-folk
-jazz
-@end smallexample
-
-@noindent
-As you can see, the system responds the same no matter whether you use
-long or short option forms.
-
-@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:
-
-@smallexample
-$ @kbd{tar -cfv collection.tar blues folk jazz}
-@end smallexample
-
-@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
-
-@noindent
-is confusing as it is. When shown using short forms, however, it
-becomes much more so:
-
-@smallexample
-$ @kbd{tar blues -c folk -f collection.tar jazz}
-@end smallexample
-
-@noindent
-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.
-
-To archive a directory, first move to its superior directory. If you
-have followed the previous instructions in this tutorial, you should
-type:
-
-@smallexample
-$ @kbd{cd ..}
-$
-@end smallexample
-
-@noindent
-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:
-
-@smallexample
-$ @kbd{tar --create --verbose --file=music.tar practice}
-@end smallexample
-
-@noindent
-@command{tar} should output:
-
-@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
-
-@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 implementations of @command{tar} may not be 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{}. In general, it is wise to always place the archive outside
-of the 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
-The output of @command{tar} would then be:
-
-@smallexample
-blues
-folk
-jazz
-@end smallexample
-
-@noindent
-The archive @file{bfiles.tar} would list as follows:
-
-@smallexample
-./birds
-baboon
-./box
-@end smallexample
-
-@noindent
-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.
-
-@xopindex{list, using with @option{--verbose}}
-@xopindex{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. This output is described in detail in @ref{verbose member listing}.
-
-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
-@xopindex{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}.
-
-Because @command{tar} preserves file names, these must be specified as
-they appear in the archive (i.e., 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.tar 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 by default are compared verbatim.
-
-However, @w{@kbd{tar --list --file=bfiles.tar baboon}} would respond
-with @file{baboon}, because this exact member name is in the archive file
-@file{bfiles.tar}. If you are not sure of the exact file name,
-use @dfn{globbing patterns}, for example:
-
-@smallexample
-$ @kbd{tar --list --file=bfiles.tar --wildcards '*b*'}
-@end smallexample
-
-@noindent
-will list all members whose name contains @samp{b}. @xref{wildcards},
-for a detailed discussion of globbing patterns and related
-@command{tar} command line options.
-
-@menu
-* list dir::
-@end menu
-
-@node list dir
-@unnumberedsubsec Listing the Contents of a Stored Directory
-
-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.
-
-For example, to find out about files in the directory @file{practice}, in
-the archive file @file{music.tar}, type:
-
-@smallexample
-$ @kbd{tar --list --verbose --file=music.tar practice}
-@end smallexample
-
-@command{tar} responds:
-
-@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
-
-When you use a directory name as a file name argument, @command{tar} acts on
-all the files (including sub-directories) in that directory.
-
-@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
-
-@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
-* extracting archives::
-* extracting files::
-* extract dir::
-* extracting untrusted archives::
-* failing commands::
-@end menu
-
-@node extracting archives
-@subsection Extracting an Entire Archive
-
-To extract an entire archive, specify the archive file name only, with
-no individual file names as arguments. For example,
-
-@smallexample
-$ @kbd{tar -xvf collection.tar}
-@end smallexample
-
-@noindent
-produces this:
-
-@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
-
-@node extracting files
-@subsection Extracting Specific Files
-
-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:
-
-@smallexample
-$ @kbd{tar --extract --file=collection.tar blues}
-@end smallexample
-
-@noindent
-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.@footnote{This is only accidentally
-true, but not in general. Whereas modification times are always
-restored, 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}).
-
-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}}. If you don't remember the
-exact member names, use @option{--list} (@option{-t}) option
-(@pxref{list}). You can also extract those members that match a
-specific @dfn{globbing pattern}. For example, to extract from
-@file{bfiles.tar} all files that begin with @samp{b}, no matter their
-directory prefix, you could type:
-
-@smallexample
-$ @kbd{tar -x -f bfiles.tar --wildcards --no-anchored 'b*'}
-@end smallexample
-
-@noindent
-Here, @option{--wildcards} instructs @command{tar} to treat
-command line arguments as globbing patterns and @option{--no-anchored}
-informs it that the patterns apply to member names after any @samp{/}
-delimiter. The use of globbing patterns is discussed in detail in
-@xref{wildcards}.
-
-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
-
-@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
-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.
-
-@node extracting untrusted archives
-@subsection Extracting Archives from Untrusted Sources
-
-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:
-
-@smallexample
-$ @kbd{mkdir newdir}
-$ @kbd{cd newdir}
-$ @kbd{tar -xvf ../untrusted.tar}
-@end smallexample
-
-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}).
-
-@node failing commands
-@subsection Commands That Will Fail
-
-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
-@end smallexample
-
-@FIXME{make sure the above works when going through the examples in
-order...}
-
-@noindent
-Likewise, if you try to use this command,
-
-@smallexample
-$ @kbd{tar -tvf music.tar folk jazz}
-@end smallexample
-
-@noindent
-you would get a similar response. Members with those names are not in the
-archive. You must use the correct member names, or wildcards, 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
-@UNREVISED
-
-@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}).
-
-@menu
-* Synopsis::
-* using tar options::
-* Styles::
-* All Options::
-* help::
-* defaults::
-* verbose::
-* checkpoints::
-* interactive::
-@end menu
-
-@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.
-
-Possible exit codes of @GNUTAR{} are summarized in the following
-table:
-
-@table @asis
-@item 0
-@samp{Successful termination}.
-
-@item 1
-@samp{Some files differ}. If tar was invoked with @option{--compare}
-(@option{--diff}, @option{-d}) command line option, this means that
-some files in the archive differ from their disk counterparts
-(@pxref{compare}). If tar was given @option{--create},
-@option{--append} or @option{--update} option, this exit code means
-that some files were changed while being archived and so the resulting
-archive does not contain the exact copy of the file set.
-
-@item 2
-@samp{Fatal error}. This means that some fatal, unrecoverable error
-occurred.
-@end table
-
-If @command{tar} has invoked a subprocess and that subprocess exited with a
-nonzero exit code, @command{tar} exits with that code as well.
-This can happen, for example, if @command{tar} was given some
-compression option (@pxref{gzip}) and the external compressor program
-failed. Another example is @command{rmt} failure during backup to the
-remote device (@pxref{Remote Tape Server}).
-
-@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. 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.
-
-@menu
-* Long Options:: Long Option Style
-* Short Options:: Short Option Style
-* Old Options:: Old Option Style
-* Mixing:: Mixing Option Styles
-@end menu
-
-@node Long Options
-@subsection Long Option Style
-
-Each option has at least one @dfn{long} (or @dfn{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 long option has many 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 long 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.)
-
-Long 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
-
-@noindent
-gives a fairly good set of hints about what the command does, even
-for those not fully acquainted with @command{tar}.
-
-Long 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 @dfn{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:
-
-@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, @dfn{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
-long option @option{--list}. So for example, the command @w{@samp{tar
-cv}} specifies the option @option{-v} in addition to the operation @option{-c}.
-
-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
-
-@noindent
-Here, @samp{20} is the argument of @option{-b} and @samp{/dev/rmt0} is
-the argument of @option{-f}.
-
-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.
-
-If you want to reorder the letters in the old option argument, be
-sure to reorder any corresponding argument appropriately.
-
-This old way of writing @command{tar} options can surprise even experienced
-users. For example, the two commands:
-
-@smallexample
-@kbd{tar cfz archive.tar.gz file}
-@kbd{tar -cfz archive.tar.gz file}
-@end smallexample
-
-@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
-
-@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 long 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.
-
-@menu
-* Operation Summary::
-* Option Summary::
-* Short Option Summary::
-@end menu
-
-@node Operation Summary
-@subsection Operations
-
-@table @option
-
-@opsummary{append}
-@item --append
-@itemx -r
-
-Appends files to the end of the archive. @xref{append}.
-
-@opsummary{catenate}
-@item --catenate
-@itemx -A
-
-Same as @option{--concatenate}. @xref{concatenate}.
-
-@opsummary{compare}
-@item --compare
-@itemx -d
-
-Compares archive members with their counterparts in the file
-system, and reports differences in file size, mode, owner,
-modification date and contents. @xref{compare}.
-
-@opsummary{concatenate}
-@item --concatenate
-@itemx -A
-
-Appends other @command{tar} archives to the end of the archive.
-@xref{concatenate}.
-
-@opsummary{create}
-@item --create
-@itemx -c
-
-Creates a new @command{tar} archive. @xref{create}.
-
-@opsummary{delete}
-@item --delete
-
-Deletes members from the archive. Don't try this on a archive on a
-tape! @xref{delete}.
-
-@opsummary{diff}
-@item --diff
-@itemx -d
-
-Same @option{--compare}. @xref{compare}.
-
-@opsummary{extract}
-@item --extract
-@itemx -x
-
-Extracts members from the archive into the file system. @xref{extract}.
-
-@opsummary{get}
-@item --get
-@itemx -x
-
-Same as @option{--extract}. @xref{extract}.
-
-@opsummary{list}
-@item --list
-@itemx -t
-
-Lists the members in an archive. @xref{list}.
-
-@opsummary{update}
-@item --update
-@itemx -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. @xref{update}.
-
-@end table
-
-@node Option Summary
-@subsection @command{tar} Options
-
-@table @option
-
-@opsummary{absolute-names}
-@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}.
-
-@opsummary{after-date}
-@item --after-date
-
-(See @option{--newer}, @pxref{after})
-
-@opsummary{anchored}
-@item --anchored
-A pattern must match an initial subsequence of the name's components.
-@xref{controlling pattern-matching}.
-
-@opsummary{atime-preserve}
-@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.
-
-@opsummary{auto-compress}
-@item --auto-compress
-@itemx -a
-
-During a @option{--create} operation, enables automatic compressed
-format recognition based on the archive suffix. @xref{gzip}.
-
-@opsummary{backup}
-@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}.
-
-@opsummary{block-number}
-@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}.
-
-@opsummary{blocking-factor}
-@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}.
-
-@opsummary{bzip2}
-@item --bzip2
-@itemx -j
-
-This option tells @command{tar} to read or write archives through
-@code{bzip2}. @xref{gzip}.
-
-@opsummary{check-device}
-@item --check-device
-Check device numbers when creating a list of modified files for
-incremental archiving. This is the default. @xref{device numbers},
-for a detailed description.
-
-@opsummary{checkpoint}
-@item --checkpoint[=@var{number}]
-
-This option directs @command{tar} to print periodic checkpoint
-messages as it reads through the archive. It is intended for when you
-want a visual indication that @command{tar} is still running, but
-don't want to see @option{--verbose} output. You can also instruct
-@command{tar} to execute a list of actions on each checkpoint, see
-@option{--checklist-action} below. For a detailed description, see
-@ref{checkpoints}.
-
-@opsummary{checkpoint-action}
-@item --checkpoint-action=@var{action}
-Instruct @command{tar} to execute an action upon hitting a
-breakpoint. Here we give only a brief outline. @xref{checkpoints},
-for a complete description.
-
-The @var{action} argument can be one of the following:
-
-@table @asis
-@item bell
-Produce an audible bell on the console.
-
-@item dot
-@itemx .
-Print a single dot on the standard listing stream.
-
-@item echo
-Display a textual message on the standard error, with the status and
-number of the checkpoint. This is the default.
-
-@item echo=@var{string}
-Display @var{string} on the standard error. Before output, the string
-is subject to meta-character expansion.
-
-@item exec=@var{command}
-Execute the given @var{command}.
-
-@item sleep=@var{time}
-Wait for @var{time} seconds.
-
-@item ttyout=@var{string}
-Output @var{string} on the current console (@file{/dev/tty}).
-@end table
-
-Several @option{--checkpoint-action} options can be specified. The
-supplied actions will be executed in order of their appearance in the
-command line.
-
-Using @option{--checkpoint-action} without @option{--checkpoint}
-assumes default checkpoint frequency of one checkpoint per 10 records.
-
-@opsummary{check-links}
-@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 @footnote{Earlier versions of @GNUTAR{} understood @option{-l} as a
-synonym for @option{--one-file-system}. The current semantics, which
-complies to UNIX98, was introduced with version
-1.15.91. @xref{Changes}, for more information.}.
-
-@xref{hard links}.
-
-@opsummary{compress}
-@opsummary{uncompress}
-@item --compress
-@itemx --uncompress
-@itemx -Z
-
-@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}.
-
-@opsummary{confirmation}
-@item --confirmation
-
-(See @option{--interactive}.) @xref{interactive}.
-
-@opsummary{delay-directory-restore}
-@item --delay-directory-restore
-
-Delay setting modification times and permissions of extracted
-directories until the end of extraction. @xref{Directory Modification Times and Permissions}.
-
-@opsummary{dereference}
-@item --dereference
-@itemx -h
-
-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}.
-
-@opsummary{directory}
-@item --directory=@var{dir}
-@itemx -C @var{dir}
-
-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}.
-
-@opsummary{exclude}
-@item --exclude=@var{pattern}
-
-When performing operations, @command{tar} will skip files that match
-@var{pattern}. @xref{exclude}.
-
-@opsummary{exclude-from}
-@item --exclude-from=@var{file}
-@itemx -X @var{file}
-
-Similar to @option{--exclude}, except @command{tar} will use the list of
-patterns in the file @var{file}. @xref{exclude}.
-
-@opsummary{exclude-caches}
-@item --exclude-caches
-
-Exclude from dump any directory containing a valid cache directory
-tag file, but still dump the directory node and the tag file itself.
-
-@xref{exclude}.
-
-@opsummary{exclude-caches-under}
-@item --exclude-caches-under
-
-Exclude from dump any directory containing a valid cache directory
-tag file, but still dump the directory node itself.
-
-@xref{exclude}.
-
-@opsummary{exclude-caches-all}
-@item --exclude-caches-all
-
-Exclude from dump any directory containing a valid cache directory
-tag file. @xref{exclude}.
-
-@opsummary{exclude-tag}
-@item --exclude-tag=@var{file}
-
-Exclude from dump any directory containing file named @var{file}, but
-dump the directory node and @var{file} itself. @xref{exclude}.
-
-@opsummary{exclude-tag-under}
-@item --exclude-tag-under=@var{file}
-
-Exclude from dump the contents of any directory containing file
-named @var{file}, but dump the directory node itself. @xref{exclude}.
-
-@opsummary{exclude-tag-all}
-@item --exclude-tag-all=@var{file}
-
-Exclude from dump any directory containing file named @var{file}.
-@xref{exclude}.
-
-@opsummary{exclude-vcs}
-@item --exclude-vcs
-
-Exclude from dump directories and files, that are internal for some
-widely used version control systems.
-
-@xref{exclude}.
-
-@opsummary{file}
-@item --file=@var{archive}
-@itemx -f @var{archive}
-
-@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}.
-
-@opsummary{files-from}
-@item --files-from=@var{file}
-@itemx -T @var{file}
-
-@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}.
-
-@opsummary{force-local}
-@item --force-local
-
-Forces @command{tar} to interpret the file name given to @option{--file}
-as a local file, even if it looks like a remote tape drive name.
-@xref{local and remote archives}.
-
-@opsummary{format}
-@item --format=@var{format}
-@itemx -H @var{format}
-
-Selects output archive format. @var{Format} may be one of the
-following:
-
-@table @samp
-@item v7
-Creates an archive that is compatible with Unix V7 @command{tar}.
-
-@item oldgnu
-Creates an archive that is compatible with GNU @command{tar} version
-1.12 or earlier.
-
-@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.
-
-@item ustar
-Creates a @acronym{POSIX.1-1988} compatible archive.
-
-@item posix
-Creates a @acronym{POSIX.1-2001 archive}.
-
-@end table
-
-@xref{Formats}, for a detailed discussion of these formats.
-
-@opsummary{group}
-@item --group=@var{group}
-
-Files added to the @command{tar} archive will have a group @acronym{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 @acronym{ID}. @xref{override}.
-
-Also see the comments for the @option{--owner=@var{user}} option.
-
-@opsummary{gzip}
-@opsummary{gunzip}
-@opsummary{ungzip}
-@item --gzip
-@itemx --gunzip
-@itemx --ungzip
-@itemx -z
-
-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}.
-
-@opsummary{hard-dereference}
-@item --hard-dereference
-When creating an archive, dereference hard links and store the files
-they refer to, instead of creating usual hard link members.
-
-@xref{hard links}.
-
-@opsummary{help}
-@item --help
-@itemx -?
-
-@command{tar} will print out a short message summarizing the operations and
-options to @command{tar} and exit. @xref{help}.
-
-@opsummary{ignore-case}
-@item --ignore-case
-Ignore case when matching member or file names with
-patterns. @xref{controlling pattern-matching}.
-
-@opsummary{ignore-command-error}
-@item --ignore-command-error
-Ignore exit codes of subprocesses. @xref{Writing to an External Program}.
-
-@opsummary{ignore-failed-read}
-@item --ignore-failed-read
-
-Do not exit unsuccessfully merely because an unreadable file was encountered.
-@xref{Reading}.
-
-@opsummary{ignore-zeros}
-@item --ignore-zeros
-@itemx -i
-
-With this option, @command{tar} will ignore zeroed blocks in the
-archive, which normally signals EOF. @xref{Reading}.
-
-@opsummary{incremental}
-@item --incremental
-@itemx -G
-
-Informs @command{tar} that it is working with an old
-@acronym{GNU}-format incremental backup archive. It is intended
-primarily for backwards compatibility only. @xref{Incremental Dumps},
-for a detailed discussion of incremental archives.
-
-@opsummary{index-file}
-@item --index-file=@var{file}
-
-Send verbose output to @var{file} instead of to standard output.
-
-@opsummary{info-script}
-@opsummary{new-volume-script}
-@item --info-script=@var{script-file}
-@itemx --new-volume-script=@var{script-file}
-@itemx -F @var{script-file}
-
-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}.
-
-@opsummary{interactive}
-@item --interactive
-@itemx --confirmation
-@itemx -w
-
-Specifies that @command{tar} should ask the user for confirmation before
-performing potentially destructive options, such as overwriting files.
-@xref{interactive}.
-
-@opsummary{keep-newer-files}
-@item --keep-newer-files
-
-Do not replace existing files that are newer than their archive copies
-when extracting files from an archive.
-
-@opsummary{keep-old-files}
-@item --keep-old-files
-@itemx -k
-
-Do not overwrite existing files when extracting files from an archive.
-@xref{Keep Old Files}.
-
-@opsummary{label}
-@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}.
-
-@opsummary{listed-incremental}
-@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. @xref{Incremental Dumps}.
-
-@opsummary{lzma}
-@item --lzma
-
-This option tells @command{tar} to read or write archives through
-@command{lzma}. @xref{gzip}.
-
-@opsummary{mode}
-@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. @var{permissions} can be specified either as an octal
-number or as symbolic permissions, like with
-@command{chmod}. @xref{override}.
-
-@opsummary{mtime}
-@item --mtime=@var{date}
-
-When adding files to an archive, @command{tar} will use @var{date} as
-the modification time of members when creating archives, instead of
-their actual modification times. The value of @var{date} can be
-either a textual date representation (@pxref{Date input formats}) or a
-name of the existing file, starting with @samp{/} or @samp{.}. In the
-latter case, the modification time of that file is used. @xref{override}.
-
-@opsummary{multi-volume}
-@item --multi-volume
-@itemx -M
-
-Informs @command{tar} that it should create or otherwise operate on a
-multi-volume @command{tar} archive. @xref{Using Multiple Tapes}.
-
-@opsummary{new-volume-script}
-@item --new-volume-script
-
-(see --info-script)
-
-@opsummary{newer}
-@item --newer=@var{date}
-@itemx --after-date=@var{date}
-@itemx -N
-
-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}.
-
-@opsummary{newer-mtime}
-@item --newer-mtime=@var{date}
-
-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). @xref{after}.
-
-@opsummary{no-anchored}
-@item --no-anchored
-An exclude pattern can match any subsequence of the name's components.
-@xref{controlling pattern-matching}.
-
-@opsummary{no-check-device}
-@item --no-check-device
-Do not check device numbers when creating a list of modified files
-for incremental archiving. @xref{device numbers}, for
-a detailed description.
-
-@opsummary{no-delay-directory-restore}
-@item --no-delay-directory-restore
-
-Modification times and permissions of extracted
-directories are set when all files from this directory have been
-extracted. This is the default.
-@xref{Directory Modification Times and Permissions}.
-
-@opsummary{no-ignore-case}
-@item --no-ignore-case
-Use case-sensitive matching.
-@xref{controlling pattern-matching}.
-
-@opsummary{no-ignore-command-error}
-@item --no-ignore-command-error
-Print warnings about subprocesses that terminated with a nonzero exit
-code. @xref{Writing to an External Program}.
-
-@opsummary{no-overwrite-dir}
-@item --no-overwrite-dir
-
-Preserve metadata of existing directories when extracting files
-from an archive. @xref{Overwrite Old Files}.
-
-@opsummary{no-quote-chars}
-@item --no-quote-chars=@var{string}
-Remove characters listed in @var{string} from the list of quoted
-characters set by the previous @option{--quote-chars} option
-(@pxref{quoting styles}).
-
-@opsummary{no-recursion}
-@item --no-recursion
-
-With this option, @command{tar} will not recurse into directories.
-@xref{recurse}.
-
-@opsummary{no-same-owner}
-@item --no-same-owner
-@itemx -o
-
-When extracting an archive, do not attempt to preserve the owner
-specified in the @command{tar} archive. This the default behavior
-for ordinary users.
-
-@opsummary{no-same-permissions}
-@item --no-same-permissions
-
-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.
-
-@opsummary{no-unquote}
-@item --no-unquote
-Treat all input file or member names literally, do not interpret
-escape sequences. @xref{input name quoting}.
-
-@opsummary{no-wildcards}
-@item --no-wildcards
-Do not use wildcards.
-@xref{controlling pattern-matching}.
-
-@opsummary{no-wildcards-match-slash}
-@item --no-wildcards-match-slash
-Wildcards do not match @samp{/}.
-@xref{controlling pattern-matching}.
-
-@opsummary{null}
-@item --null
-
-When @command{tar} is using the @option{--files-from} option, this option
-instructs @command{tar} to expect file names terminated with @acronym{NUL}, so
-@command{tar} can correctly work with file names that contain newlines.
-@xref{nul}.
-
-@opsummary{numeric-owner}
-@item --numeric-owner
-
-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}.
-
-@item -o
-The function of this option depends on the action @command{tar} is
-performing. When extracting files, @option{-o} is a synonym for
-@option{--no-same-owner}, i.e., it prevents @command{tar} from
-restoring ownership of files being extracted.
-
-When creating an archive, it is a synonym for
-@option{--old-archive}. This behavior is for compatibility
-with previous versions of @GNUTAR{}, and will be
-removed in future releases.
-
-@xref{Changes}, for more information.
-
-@opsummary{occurrence}
-@item --occurrence[=@var{number}]
-
-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.
-
-This option instructs @command{tar} to process only the @var{number}th
-occurrence of each named file. @var{Number} defaults to 1, so
-
-@smallexample
-tar -x -f archive.tar --occurrence filename
-@end smallexample
-
-@noindent
-will extract the first occurrence of the member @file{filename} from @file{archive.tar}
-and will terminate without scanning to the end of the archive.
-
-@opsummary{old-archive}
-@item --old-archive
-Synonym for @option{--format=v7}.
-
-@opsummary{one-file-system}
-@item --one-file-system
-Used when creating an archive. Prevents @command{tar} from recursing into
-directories that are on different file systems from the current
-directory.
-
-@opsummary{overwrite}
-@item --overwrite
-
-Overwrite existing files and directory metadata when extracting files
-from an archive. @xref{Overwrite Old Files}.
-
-@opsummary{overwrite-dir}
-@item --overwrite-dir
-
-Overwrite the metadata of existing directories when extracting files
-from an archive. @xref{Overwrite Old Files}.
-
-@opsummary{owner}
-@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 @acronym{ID}.
-@xref{override}.
-
-This option does not affect extraction from archives.
-
-@opsummary{pax-option}
-@item --pax-option=@var{keyword-list}
-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. @xref{PAX keywords}, for a detailed
-discussion.
-
-@opsummary{portability}
-@item --portability
-@itemx --old-archive
-Synonym for @option{--format=v7}.
-
-@opsummary{posix}
-@item --posix
-Same as @option{--format=posix}.
-
-@opsummary{preserve}
-@item --preserve
-
-Synonymous with specifying both @option{--preserve-permissions} and
-@option{--same-order}. @xref{Setting Access Permissions}.
-
-@opsummary{preserve-order}
-@item --preserve-order
-
-(See @option{--same-order}; @pxref{Reading}.)
-
-@opsummary{preserve-permissions}
-@opsummary{same-permissions}
-@item --preserve-permissions
-@itemx --same-permissions
-@itemx -p
-
-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}.
-
-@opsummary{quote-chars}
-@item --quote-chars=@var{string}
-Always quote characters from @var{string}, even if the selected
-quoting style would not quote them (@pxref{quoting styles}).
-
-@opsummary{quoting-style}
-@item --quoting-style=@var{style}
-Set quoting style to use when printing member and file names
-(@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.
-
-@opsummary{read-full-records}
-@item --read-full-records
-@itemx -B
-
-Specifies that @command{tar} should reblock its input, for reading
-from pipes on systems with buggy implementations. @xref{Reading}.
-
-@opsummary{record-size}
-@item --record-size=@var{size}
-
-Instructs @command{tar} to use @var{size} bytes per record when accessing the
-archive. @xref{Blocking Factor}.
-
-@opsummary{recursion}
-@item --recursion
-
-With this option, @command{tar} recurses into directories (default).
-@xref{recurse}.
-
-@opsummary{recursive-unlink}
-@item --recursive-unlink
-
-Remove existing
-directory hierarchies before extracting directories of the same name
-from the archive. @xref{Recursive Unlink}.
-
-@opsummary{remove-files}
-@item --remove-files
-
-Directs @command{tar} to remove the source file from the file system after
-appending it to an archive. @xref{remove files}.
-
-@opsummary{restrict}
-@item --restrict
-
-Disable use of some potentially harmful @command{tar} options.
-Currently this option disables shell invocation from multi-volume menu
-(@pxref{Using Multiple Tapes}).
-
-@opsummary{rmt-command}
-@item --rmt-command=@var{cmd}
-
-Notifies @command{tar} that it should use @var{cmd} instead of
-the default @file{/usr/libexec/rmt} (@pxref{Remote Tape Server}).
-
-@opsummary{rsh-command}
-@item --rsh-command=@var{cmd}
-
-Notifies @command{tar} that is should use @var{cmd} to communicate with remote
-devices. @xref{Device}.
-
-@opsummary{same-order}
-@item --same-order
-@itemx --preserve-order
-@itemx -s
-
-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}.
-
-@opsummary{same-owner}
-@item --same-owner
-
-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}.
-
-@opsummary{same-permissions}
-@item --same-permissions
-
-(See @option{--preserve-permissions}; @pxref{Setting Access Permissions}.)
-
-@opsummary{seek}
-@item --seek
-@itemx -n
-
-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.
-
-@opsummary{show-defaults}
-@item --show-defaults
-
-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:
-
-@smallexample
-$ tar --show-defaults
---format=gnu -f- -b20 --quoting-style=escape \
---rmt-command=/usr/libexec/rmt --rsh-command=/usr/bin/rsh
-@end smallexample
-
-@opsummary{show-omitted-dirs}
-@item --show-omitted-dirs
-
-Instructs @command{tar} to mention the directories it is skipping when
-operating on a @command{tar} archive. @xref{show-omitted-dirs}.
-
-@opsummary{show-transformed-names}
-@opsummary{show-stored-names}
-@item --show-transformed-names
-@itemx --show-stored-names
-
-Display file or member names after applying any transformations
-(@pxref{transform}). In particular, when used in conjunction with one of
-the archive creation operations it instructs @command{tar} to list the
-member names stored in the archive, as opposed to the actual file
-names. @xref{listing member and file names}.
-
-@opsummary{sparse}
-@item --sparse
-@itemx -S
-
-Invokes a @acronym{GNU} extension when adding files to an archive that handles
-sparse files efficiently. @xref{sparse}.
-
-@opsummary{sparse-version}
-@item --sparse-version=@var{version}
-
-Specifies the @dfn{format version} to use when archiving sparse
-files. Implies @option{--sparse}. @xref{sparse}. For the description
-of the supported sparse formats, @xref{Sparse Formats}.
-
-@opsummary{starting-file}
-@item --starting-file=@var{name}
-@itemx -K @var{name}
-
-This option affects extraction only; @command{tar} will skip extracting
-files in the archive until it finds one that matches @var{name}.
-@xref{Scarce}.
-
-@opsummary{strip-components}
-@item --strip-components=@var{number}
-Strip given @var{number} of leading components from file names before
-extraction. For example, if archive @file{archive.tar} contained
-@file{/some/file/name}, then running
-
-@smallexample
-tar --extract --file archive.tar --strip-components=2
-@end smallexample
-
-@noindent
-would extract this file to file @file{name}.
-
-@opsummary{suffix}, summary
-@item --suffix=@var{suffix}
-
-Alters the suffix @command{tar} uses when backing up files from the default
-@samp{~}. @xref{backup}.
-
-@opsummary{tape-length}
-@item --tape-length=@var{num}
-@itemx -L @var{num}
-
-Specifies the length of tapes that @command{tar} is writing as being
-@w{@var{num} x 1024} bytes long. @xref{Using Multiple Tapes}.
-
-@opsummary{test-label}
-@item --test-label
-
-Reads the volume label. If an argument is specified, test whether it
-matches the volume label. @xref{--test-label option}.
-
-@opsummary{to-command}
-@item --to-command=@var{command}
-
-During extraction @command{tar} will pipe extracted files to the
-standard input of @var{command}. @xref{Writing to an External Program}.
-
-@opsummary{to-stdout}
-@item --to-stdout
-@itemx -O
-
-During extraction, @command{tar} will extract files to stdout rather
-than to the file system. @xref{Writing to Standard Output}.
-
-@opsummary{totals}
-@item --totals[=@var{signo}]
-
-Displays the total number of bytes transferred when processing an
-archive. If an argument is given, these data are displayed on
-request, when signal @var{signo} is delivered to @command{tar}.
-@xref{totals}.
-
-@opsummary{touch}
-@item --touch
-@itemx -m
-
-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}.
-
-@opsummary{transform}
-@item --transform=@var{sed-expr}
-
-Transform file or member names using @command{sed} replacement expression
-@var{sed-expr}. For example,
-
-@smallexample
-$ @kbd{tar cf archive.tar --transform 's,^\./,usr/,' .}
-@end smallexample
-
-@noindent
-will add to @file{archive} files from the current working directory,
-replacing initial @samp{./} prefix with @samp{usr/}. For the detailed
-discussion, @xref{transform}.
-
-To see transformed member names in verbose listings, use
-@option{--show-transformed-names} option
-(@pxref{show-transformed-names}).
-
-@opsummary{uncompress}
-@item --uncompress
-
-(See @option{--compress}. @pxref{gzip})
-
-@opsummary{ungzip}
-@item --ungzip
-
-(See @option{--gzip}. @pxref{gzip})
-
-@opsummary{unlink-first}
-@item --unlink-first
-@itemx -U
-
-Directs @command{tar} to remove the corresponding file from the file
-system before extracting it from the archive. @xref{Unlink First}.
-
-@opsummary{unquote}
-@item --unquote
-Enable unquoting input file or member names (default). @xref{input
-name quoting}.
-
-@opsummary{use-compress-program}
-@item --use-compress-program=@var{prog}
-
-Instructs @command{tar} to access the archive through @var{prog}, which is
-presumed to be a compression program of some sort. @xref{gzip}.
-
-@opsummary{utc}
-@item --utc
-
-Display file modification dates in @acronym{UTC}. This option implies
-@option{--verbose}.
-
-@opsummary{verbose}
-@item --verbose
-@itemx -v
-
-Specifies that @command{tar} should be more verbose about the
-operations it is performing. This option can be specified multiple
-times for some operations to increase the amount of information displayed.
-@xref{verbose}.
-
-@opsummary{verify}
-@item --verify
-@itemx -W
-
-Verifies that the archive was correctly written when creating an
-archive. @xref{verify}.
-
-@opsummary{version}
-@item --version
-
-Print information about the program's name, version, origin and legal
-status, all on standard output, and then exit successfully.
-@xref{help}.
-
-@opsummary{volno-file}
-@item --volno-file=@var{file}
-
-Used in conjunction with @option{--multi-volume}. @command{tar} will
-keep track of which volume of a multi-volume archive it is working in
-@var{file}. @xref{volno-file}.
-
-@opsummary{wildcards}
-@item --wildcards
-Use wildcards when matching member names with patterns.
-@xref{controlling pattern-matching}.
-
-@opsummary{wildcards-match-slash}
-@item --wildcards-match-slash
-Wildcards match @samp{/}.
-@xref{controlling pattern-matching}.
-@end table
-
-@node Short Option Summary
-@subsection Short Options Cross Reference
-
-Here is an alphabetized list of all of the short option forms, matching
-them with the equivalent long option.
-
-@multitable @columnfractions 0.20 0.80
-@headitem Short Option @tab Reference
-
-@item -A @tab @ref{--concatenate}.
-
-@item -B @tab @ref{--read-full-records}.
-
-@item -C @tab @ref{--directory}.
-
-@item -F @tab @ref{--info-script}.
-
-@item -G @tab @ref{--incremental}.
-
-@item -K @tab @ref{--starting-file}.
-
-@item -L @tab @ref{--tape-length}.
-
-@item -M @tab @ref{--multi-volume}.
-
-@item -N @tab @ref{--newer}.
-
-@item -O @tab @ref{--to-stdout}.
-
-@item -P @tab @ref{--absolute-names}.
-
-@item -R @tab @ref{--block-number}.
-
-@item -S @tab @ref{--sparse}.
-
-@item -T @tab @ref{--files-from}.
-
-@item -U @tab @ref{--unlink-first}.
-
-@item -V @tab @ref{--label}.
-
-@item -W @tab @ref{--verify}.
-
-@item -X @tab @ref{--exclude-from}.
-
-@item -Z @tab @ref{--compress}.
-
-@item -b @tab @ref{--blocking-factor}.
-
-@item -c @tab @ref{--create}.
-
-@item -d @tab @ref{--compare}.
-
-@item -f @tab @ref{--file}.
-
-@item -g @tab @ref{--listed-incremental}.
-
-@item -h @tab @ref{--dereference}.
-
-@item -i @tab @ref{--ignore-zeros}.
-
-@item -j @tab @ref{--bzip2}.
-
-@item -k @tab @ref{--keep-old-files}.
-
-@item -l @tab @ref{--check-links}.
-
-@item -m @tab @ref{--touch}.
-
-@item -o @tab When creating, @ref{--no-same-owner}, when extracting ---
-@ref{--portability}.
-
-The later usage is deprecated. It is retained for compatibility with
-the earlier versions of @GNUTAR{}. In future releases
-@option{-o} will be equivalent to @option{--no-same-owner} only.
-
-@item -p @tab @ref{--preserve-permissions}.
-
-@item -r @tab @ref{--append}.
-
-@item -s @tab @ref{--same-order}.
-
-@item -t @tab @ref{--list}.
-
-@item -u @tab @ref{--update}.
-
-@item -v @tab @ref{--verbose}.
-
-@item -w @tab @ref{--interactive}.
-
-@item -x @tab @ref{--extract}.
-
-@item -z @tab @ref{--gzip}.
-
-@end multitable
-
-@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) @value{VERSION}
-Copyright (C) 2008 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
-@xopindex{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 be 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
-explicitly 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 --quoting-style=escape
---rmt-command=/etc/rmt --rsh-command=/usr/bin/rsh
-@end group
-@end smallexample
-
-@noindent
-Notice, that this option outputs only one line. The example output above
-has been split to fit page boundaries.
-
-@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
-(@xref{verbose member listing}, for the description) 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.
-
-@anchor{totals}
-@cindex Obtaining total status information
-@opindex totals
-The @option{--totals} option causes @command{tar} to print on the
-standard error the total amount of bytes transferred when processing
-an archive. When creating or appending to an archive, this option
-prints the number of bytes written to the archive and the average
-speed at which they have been written, e.g.:
-
-@smallexample
-@group
-$ @kbd{tar -c -f archive.tar --totals /home}
-Total bytes written: 7924664320 (7.4GiB, 85MiB/s)
-@end group
-@end smallexample
-
-When reading an archive, this option displays the number of bytes
-read:
-
-@smallexample
-@group
-$ @kbd{tar -x -f archive.tar --totals}
-Total bytes read: 7924664320 (7.4GiB, 95MiB/s)
-@end group
-@end smallexample
-
-Finally, when deleting from an archive, the @option{--totals} option
-displays both numbers plus number of bytes removed from the archive:
-
-@smallexample
-@group
-$ @kbd{tar --delete -f foo.tar --totals --wildcards '*~'}
-Total bytes read: 9543680 (9.2MiB, 201MiB/s)
-Total bytes written: 3829760 (3.7MiB, 81MiB/s)
-Total bytes deleted: 1474048
-@end group
-@end smallexample
-
-You can also obtain this information on request. When
-@option{--totals} is used with an argument, this argument is
-interpreted as a symbolic name of a signal, upon delivery of which the
-statistics is to be printed:
-
-@table @option
-@item --totals=@var{signo}
-Print statistics upon delivery of signal @var{signo}. Valid arguments
-are: @code{SIGHUP}, @code{SIGQUIT}, @code{SIGINT}, @code{SIGUSR1} and
-@code{SIGUSR2}. Shortened names without @samp{SIG} prefix are also
-accepted.
-@end table
-
-Both forms of @option{--totals} option can be used simultaneously.
-Thus, @kbd{tar -x --totals --totals=USR1} instructs @command{tar} to
-extract all members from its default archive and print statistics
-after finishing the extraction, as well as when receiving signal
-@code{SIGUSR1}.
-
-@anchor{Progress information}
-@cindex Progress information
-The @option{--checkpoint} option prints an occasional message
-as @command{tar} reads or writes the archive. 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. By default it
-prints a message each 10 records read or written. This can be changed
-by giving it a numeric argument after an equal sign:
-
-@smallexample
-$ @kbd{tar -c --checkpoint=1000} /var
-tar: Write checkpoint 1000
-tar: Write checkpoint 2000
-tar: Write checkpoint 3000
-@end smallexample
-
-This example shows the default checkpoint message used by
-@command{tar}. If you place a dot immediately after the equal
-sign, it will print a @samp{.} at each checkpoint@footnote{This is
-actually a shortcut for @option{--checkpoint=@var{n}
---checkpoint-action=dot}. @xref{checkpoints, dot}.}. For example:
-
-@smallexample
-$ @kbd{tar -c --checkpoint=.1000} /var
-...
-@end smallexample
-
-The @option{--checkpoint} option provides a flexible mechanism for
-executing arbitrary actions upon hitting checkpoints, see the next
-section (@pxref{checkpoints}), for more information on it.
-
-@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 checkpoints
-@section Checkpoints
-@cindex checkpoints, defined
-@opindex checkpoint
-@opindex checkpoint-action
-
-A @dfn{checkpoint} is a moment of time before writing @var{n}th record to
-the archive (a @dfn{write checkpoint}), or before reading @var{n}th record
-from the archive (a @dfn{read checkpoint}). Checkpoints allow to
-periodically execute arbitrary actions.
-
-The checkpoint facility is enabled using the following option:
-
-@table @option
-@xopindex{checkpoint, defined}
-@item --checkpoint[=@var{n}]
-Schedule checkpoints before writing or reading each @var{n}th record.
-The default value for @var{n} is 10.
-@end table
-
-A list of arbitrary @dfn{actions} can be executed at each checkpoint.
-These actions include: pausing, displaying textual messages, and
-executing arbitrary external programs. Actions are defined using
-the @option{--checkpoint-action} option.
-
-@table @option
-@xopindex{checkpoint-action, defined}
-@item --checkpoint-action=@var{action}
-Execute an @var{action} at each checkpoint.
-@end table
-
-@cindex @code{echo}, checkpoint action
-The simplest value of @var{action} is @samp{echo}. It instructs
-@command{tar} to display the default message on the standard error
-stream upon arriving at each checkpoint. The default message is (in
-@acronym{POSIX} locale) @samp{Write checkpoint @var{n}}, for write
-checkpoints, and @samp{Read checkpoint @var{n}}, for read checkpoints.
-Here, @var{n} represents ordinal number of the checkpoint.
-
-In another locales, translated versions of this message are used.
-
-This is the default action, so running:
-
-@smallexample
-$ @kbd{tar -c --checkpoint=1000 --checkpoint-action=echo} /var
-@end smallexample
-
-@noindent
-is equivalent to:
-
-@smallexample
-$ @kbd{tar -c --checkpoint=1000} /var
-@end smallexample
-
-The @samp{echo} action also allows to supply a customized message.
-You do so by placing an equals sign and the message right after it,
-e.g.:
-
-@smallexample
---checkpoint-action="echo=Hit %s checkpoint #%u"
-@end smallexample
-
-The @samp{%s} and @samp{%u} in the above example are
-@dfn{meta-characters}. The @samp{%s} meta-character is replaced with
-the @dfn{type} of the checkpoint: @samp{write} or
-@samp{read} (or a corresponding translated version in locales other
-than @acronym{POSIX}). The @samp{%u} meta-character is replaced with
-the ordinal number of the checkpoint. Thus, the above example could
-produce the following output when used with the @option{--create}
-option:
-
-@smallexample
-tar: Hit write checkpoint #10
-tar: Hit write checkpoint #20
-tar: Hit write checkpoint #30
-@end smallexample
-
-Aside from meta-character expansion, the message string is subject to
-@dfn{unquoting}, during which the backslash @dfn{escape sequences} are
-replaced with their corresponding @acronym{ASCII} characters
-(@pxref{escape sequences}). E.g. the following action will produce an
-audible bell and the message described above at each checkpoint:
-
-@smallexample
---checkpoint-action='echo=\aHit %s checkpoint #%u'
-@end smallexample
-
-@cindex @code{bell}, checkpoint action
-There is also a special action which produces an audible signal:
-@samp{bell}. It is not equivalent to @samp{echo='\a'}, because
-@samp{bell} sends the bell directly to the console (@file{/dev/tty}),
-whereas @samp{echo='\a'} sends it to the standard error.
-
-@cindex @code{ttyout}, checkpoint action
-The @samp{ttyout=@var{string}} action outputs @var{string} to
-@file{/dev/tty}, so it can be used even if the standard output is
-redirected elsewhere. The @var{string} is subject to the same
-modifications as with @samp{echo} action. In contrast to the latter,
-@samp{ttyout} does not prepend @command{tar} executable name to the
-string, nor does it output a newline after it. For example, the
-following action will print the checkpoint message at the same screen
-line, overwriting any previous message:
-
-@smallexample
---checkpoint-action="ttyout=\rHit %s checkpoint #%u"
-@end smallexample
-
-@cindex @code{dot}, checkpoint action
-Another available checkpoint action is @samp{dot} (or @samp{.}). It
-instructs @command{tar} to print a single dot on the standard listing
-stream, e.g.:
-
-@smallexample
-$ @kbd{tar -c --checkpoint=1000 --checkpoint-action=dot} /var
-...
-@end smallexample
-
-For compatibility with previous @GNUTAR{} versions, this action can
-be abbreviated by placing a dot in front of the checkpoint frequency,
-as shown in the previous section.
-
-@cindex @code{sleep}, checkpoint action
-Yet another action, @samp{sleep}, pauses @command{tar} for a specified
-amount of seconds. The following example will stop for 30 seconds at each
-checkpoint:
-
-@smallexample
-$ @kbd{tar -c --checkpoint=1000 --checkpoint-action=sleep=30}
-@end smallexample
-
-@cindex @code{exec}, checkpoint action
-Finally, the @code{exec} action executes a given external program.
-For example:
-
-@smallexample
-$ @kbd{tar -c --checkpoint=1000 --checkpoint-action=exec=/sbin/cpoint}
-@end smallexample
-
-This program is executed using @command{/bin/sh -c}, with no
-additional arguments. Its exit code is ignored. It gets a copy of
-@command{tar}'s environment plus the following variables:
-
-@table @env
-@vrindex TAR_VERSION, checkpoint script environment
-@item TAR_VERSION
-@GNUTAR{} version number.
-
-@vrindex TAR_ARCHIVE, checkpoint script environment
-@item TAR_ARCHIVE
-The name of the archive @command{tar} is processing.
-
-@vrindex TAR_BLOCKING_FACTOR, checkpoint script environment
-@item TAR_BLOCKING_FACTOR
-Current blocking factor (@pxref{Blocking}.
-
-@vrindex TAR_CHECKPOINT, checkpoint script environment
-@item TAR_CHECKPOINT
-The checkpoint number.
-
-@vrindex TAR_SUBCOMMAND, checkpoint script environment
-@item TAR_SUBCOMMAND
-A short option describing the operation @command{tar} is executing
-@xref{Operations}, for a complete list of subcommand options.
-
-@vrindex TAR_FORMAT, checkpoint script environment
-@item TAR_FORMAT
-Format of the archive being processed. @xref{Formats}, for a complete
-list of archive format names.
-@end table
-
-Any number of actions can be defined, by supplying several
-@option{--checkpoint-action} options in the command line. For
-example, the command below displays two messages, pauses
-execution for 30 seconds and executes the @file{/sbin/cpoint} script:
-
-@example
-@group
-$ @kbd{tar -c -f arc.tar \
- --checkpoint-action='\aecho=Hit %s checkpoint #%u' \
- --checkpoint-action='echo=Sleeping for 30 seconds' \
- --checkpoint-action='sleep=30' \
- --checkpoint-action='exec=/sbin/cpoint'}
-@end group
-@end example
-
-This example also illustrates the fact that
-@option{--checkpoint-action} can be used without
-@option{--checkpoint}. In this case, the default checkpoint frequency
-(at each 10th record) is assumed.
-
-@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
-@xopindex{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 catastrophic 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
-
-@xopindex{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.cl.cam.ac.uk/@/~mgk25/@/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}. The archive @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
-
-@node multiple
-@subsubsection Multiple Members 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}; @xref{update}, for more information.
-We describe this use of @option{--append} here for the sake of
-completeness.) 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. @xref{multiple}, for a detailed discussion.
-
-@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).
-
-@c note: the above parenthetical added because in fact, this
-@c 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.
-@footnote{This can cause multiple members to have the same name, for
-information on how this affects reading the archive, @ref{multiple}.}
-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
-rock
-$ @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 jazzfolk.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{bluesrock.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
-folk
-jazz
-@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
-$ @kbd{tar --delete --file=collection.tar blues}
-$ @kbd{tar --list --file=collection.tar}
-folk
-jazz
-rock
-$
-@end smallexample
-
-@FIXME{Check if the above listing is actually produced after running
-all the examples on collection.tar.}
-
-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}
-
-@xopindex{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
-* override:: Overriding File Metadata.
-* Ignore Failed Read::
-@end menu
-
-@node override
-@subsection Overriding File Metadata
-
-As described above, a @command{tar} archive keeps, for each member it contains,
-its @dfn{metadata}, such as modification time, mode and ownership of
-the file. @GNUTAR{} allows to replace these data with other values
-when adding files to the archive. The options described in this
-section affect creation of archives of any type. For POSIX archives,
-see also @ref{PAX keywords}, for additional ways of controlling
-metadata, stored in the archive.
-
-@table @option
-@opindex mode
-@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. @var{permissions} can be specified either as an octal
-number or as symbolic permissions, like with
-@command{chmod} (@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). Using latter syntax allows for
-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:
-
-@smallexample
-$ @kbd{tar -c -f archive.tar --mode='a+rw' .}
-@end smallexample
-
-@item --mtime=@var{date}
-@opindex mtime
-
-When adding files to an archive, @command{tar} will use @var{date} as
-the modification time of members when creating archives, instead of
-their actual modification times. The argument @var{date} can be
-either a textual date representation in almost arbitrary format
-(@pxref{Date input formats}) or a name of the existing file, starting
-with @samp{/} or @samp{.}. In the latter case, the modification time
-of that file will be used.
-
-The following example will set the modification date to 00:00:00 UTC,
-January 1, 1970:
-
-@smallexample
-$ @kbd{tar -c -f archive.tar --mtime='1970-01-01' .}
-@end smallexample
-
-@noindent
-When used with @option{--verbose} (@pxref{verbose tutorial}) @GNUTAR{}
-will try to convert the specified date back to its textual
-representation and compare it with the one given with
-@option{--mtime} options. If the two dates differ, @command{tar} will
-print a warning saying what date it will use. This is to help user
-ensure he is using the right date.
-
-For example:
-
-@smallexample
-$ @kbd{tar -c -f archive.tar -v --mtime=yesterday .}
-tar: Option --mtime: Treating date `yesterday' as 2006-06-20
-13:06:29.152478
-@dots{}
-@end smallexample
-
-@item --owner=@var{user}
-@opindex owner
-
-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. The argument @var{user} can be either an existing user symbolic
-name, or a decimal numeric user @acronym{ID}.
-
-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. For example:
-
-@smallexample
-@group
-$ @kbd{tar -c -f archive.tar --owner=0 .}
-# @r{Or:}
-$ @kbd{tar -c -f archive.tar --owner=root .}
-@end group
-@end smallexample
-
-@item --group=@var{group}
-@opindex group
-
-Files added to the @command{tar} archive will have a group @acronym{ID} of @var{group},
-rather than the group from the source file. The argument @var{group}
-can be either an existing group symbolic name, or a decimal numeric group @acronym{ID}.
-@end table
-
-@node Ignore Failed Read
-@subsection Ignore Fail Read
-
-@table @option
-@item --ignore-failed-read
-@opindex 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
-
-@xopindex{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 @acronym{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 compatibility 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
-
-@xopindex{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
-@xopindex{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.
-
-@xopindex{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.
-
-@xopindex{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.
-
-@table @option
-@opindex preserve-permissions
-@opindex same-permissions
-@item --preserve-permissions
-@itemx --same-permissions
-@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 successfully 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
-remembers all restored directories, and restores their meta-data
-only after the entire archive has been processed. Notice, that you do
-not need to specify 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
-
-However, @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-command
-@item --to-command=@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 @env
-@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 section is too terse. Something more to add? An example,
-maybe?}
-
-@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
-
-@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
-You can avoid subshells by using @option{-C} option:
-
-@smallexample
-$ @kbd{tar -C sourcedir -cf - . | tar -C targetdir -xf -}
-@end smallexample
-
-@noindent
-The command also works using short option forms:
-
-@smallexample
-$ @kbd{(cd sourcedir; tar --create --file=- . ) \
- | (cd targetdir; tar --extract --file=-)}
-# Or:
-$ @kbd{tar --directory sourcedir --create --file=- . ) \
- | tar --directory targetdir --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 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.
-
-@anchor{device numbers}
-@cindex Device numbers, using in incremental backups
-Metadata stored in snapshot files include device numbers, which,
-obviously are supposed to be a non-volatile values. However, it turns
-out that @acronym{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 @acronym{NFS} devices numbers over time. The solution implemented
-currently is to considers all @acronym{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.
-
-Apart from using @acronym{NFS}, there are a number of cases where
-relying on device numbers can cause spurious redumping of unmodified
-files. For example, this occurs when archiving @acronym{LVM} snapshot
-volumes. To avoid this, use @option{--no-check-device} option:
-
-@table @option
-@xopindex{no-check-device, described}
-@item --no-check-device
-Do not rely on device numbers when preparing a list of changed files
-for an incremental dump.
-
-@xopindex{check-device, described}
-@item --check-device
-Use device numbers when preparing a list of changed files
-for an incremental dump. This is the default behavior. The purpose
-of this option is to undo the effect of the @option{--no-check-device}
-if it was given in @env{TAR_OPTIONS} environment variable
-(@pxref{TAR_OPTIONS}).
-@end table
-
-There is also another way to cope with changing device numbers. It is
-described in detail in @ref{Fixing Snapshot Files}.
-
-Note that incremental archives use @command{tar} extensions and may
-not be readable by non-@acronym{GNU} versions of the @command{tar} program.
-
-@xopindex{listed-incremental, using with @option{--extract}}
-@xopindex{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 without @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.
-
-@xopindex{incremental, using with @option{--list}}
-@xopindex{listed-incremental, using with @option{--list}}
-@xopindex{list, using with @option{--incremental}}
-@xopindex{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 inconvenient
-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). @xref{Dumpdir}, for the detailed
-description of dumpdirs and status codes. 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 (i.e., 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 @acronym{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
-
-The name of the file that contains a list of 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
-
-The name of the file that contains a list of 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 machines. 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, and will expect confirmation from the console. For the
-description of the default prompt, see @ref{change volume prompt}.
-
-@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 file name of 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. Default @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. Default @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. @xref{Tape Positioning}, 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
-
-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.
-
-This chapter discusses these options in detail.
-
-@menu
-* file:: Choosing the Archive's Name
-* Selecting Archive Members::
-* files:: Reading Names from a File
-* exclude:: Excluding Some Files
-* wildcards:: Wildcards Patterns and Matching
-* quoting styles:: Ways of Quoting Special Characters in Names
-* transform:: Modifying File and Member Names
-* after:: Operating Only on New Files
-* recurse:: Descending into Directories
-* one:: Crossing File System Boundaries
-@end menu
-
-@node file
-@section Choosing and Naming Archive Files
-@UNREVISED
-
-@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 have 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
-@xopindex{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 (i.e., @file{/dev/tu00}).
-
-@cindex Standard input and output
-@cindex tar to standard input and output
-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.
-
-The following example is a convenient way of copying directory
-hierarchy from @file{sourcedir} to @file{targetdir}.
-
-@smallexample
-$ @kbd{(cd sourcedir; tar -cf - .) | (cd targetdir; tar -xpf -)}
-@end smallexample
-
-The @option{-C} option allows to avoid using subshells:
-
-@smallexample
-$ @kbd{tar -C sourcedir -cf - . | tar -C targetdir -xpf -}
-@end smallexample
-
-In both examples above, the leftmost @command{tar} invocation archives
-the contents of @file{sourcedir} to the standard output, while the
-rightmost one reads this archive from its standard input and
-extracts it. The @option{-p} option tells it to restore permissions
-of the extracted files.
-
-@cindex Remote devices
-@cindex tar to a remote device
-@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.
-
-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{-}), precede it with
-@option{--add-file} option to prevent it from being treated as an
-option.
-
-@anchor{input name quoting}
-By default @GNUTAR{} attempts to @dfn{unquote} each file or member
-name, replacing @dfn{escape sequences} according to the following
-table:
-
-@multitable @columnfractions 0.20 0.60
-@headitem Escape @tab Replaced with
-@item \a @tab Audible bell (@acronym{ASCII} 7)
-@item \b @tab Backspace (@acronym{ASCII} 8)
-@item \f @tab Form feed (@acronym{ASCII} 12)
-@item \n @tab New line (@acronym{ASCII} 10)
-@item \r @tab Carriage return (@acronym{ASCII} 13)
-@item \t @tab Horizontal tabulation (@acronym{ASCII} 9)
-@item \v @tab Vertical tabulation (@acronym{ASCII} 11)
-@item \? @tab @acronym{ASCII} 127
-@item \@var{n} @tab @acronym{ASCII} @var{n} (@var{n} should be an octal number
- of up to 3 digits)
-@end multitable
-
-A backslash followed by any other symbol is retained.
-
-This default behavior is controlled by the following command line
-option:
-
-@table @option
-@opindex unquote
-@item --unquote
-Enable unquoting input file or member names (default).
-
-@opindex no-unquote
-@item --no-unquote
-Disable unquoting input file or member names.
-@end table
-
-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, @command{tar} behavior differs depending
-on the operation mode as described below:
-
-When @command{tar} is invoked with @option{--create} (@option{-c}),
-@command{tar} will stop immediately, reporting the following:
-
-@smallexample
-@group
-$ @kbd{tar cf a.tar}
-tar: Cowardly refusing to create an empty archive
-Try `tar --help' or `tar --usage' for more information.
-@end group
-@end smallexample
-
-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 run with @option{--diff} option, tar will compare the archive with
-the contents of the current working directory.
-
-If you specify any other operation, @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. 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.
-
-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
-@xopindex{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.
-
-Notice, that lines from @var{file} are read verbatim. One of the
-frequent errors is leaving some extra whitespace after a file name,
-which is difficult to catch using text editors.
-
-However, empty lines are OK.
-
-@cindex version control system, excluding files
-@cindex VCS, excluding files
-@cindex SCCS, excluding files
-@cindex RCS, excluding files
-@cindex CVS, excluding files
-@cindex SVN, excluding files
-@cindex git, excluding files
-@table @option
-@opindex exclude-vcs
-@item --exclude-vcs
-Exclude files and directories used by some version control systems.
-@end table
-
-As of version @value{VERSION}, the following files are excluded:
-
-@itemize @bullet
-@item @file{CVS/}, and everything under it
-@item @file{RCS/}, and everything under it
-@item @file{SCCS/}, and everything under it
-@item @file{.git/}, and everything under it
-@item @file{.gitignore}
-@item @file{.cvsignore}
-@item @file{.svn/}, and everything under it
-@item @file{.arch-ids/}, and everything under it
-@item @file{@{arch@}/}, and everything under it
-@item @file{=RELEASE-ID}
-@item @file{=meta-update}
-@item @file{=update}
-@end itemize
-
-@findex exclude-caches
-When creating an archive, the @option{--exclude-caches} option family
-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.
-
-There are three @samp{exclude-caches} options, each providing a different
-exclusion semantics:
-
-@table @option
-@opindex exclude-caches
-@item --exclude-caches
-Do not archive the contents of the directory, but archive the
-directory itself and the @file{CACHEDIR.TAG} file.
-
-@opindex exclude-caches-under
-@item --exclude-caches-under
-Do not archive the contents of the directory, nor the
-@file{CACHEDIR.TAG} file, archive only the directory itself.
-
-@opindex exclude-caches-all
-@item --exclude-caches-all
-Omit directories containing @file{CACHEDIR.TAG} file entirely.
-@end table
-
-@findex exclude-tag
-Another option family, @option{--exclude-tag}, provides a generalization of
-this concept. It takes a single argument, a file name to look for.
-Any directory that contains this file will be excluded from the dump.
-Similarly to @samp{exclude-caches}, there are three options in this
-option family:
-
-@table @option
-@opindex exclude-tag
-@item --exclude-tag=@var{file}
-Do not dump the contents of the directory, but dump the
-directory itself and the @var{file}.
-
-@opindex exclude-tag-under
-@item --exclude-tag-under=@var{file}
-Do not dump the contents of the directory, nor the
-@var{file}, archive only the directory itself.
-
-@opindex exclude-tag-all
-@item --exclude-tag-all=@var{file}
-Omit directories containing @var{file} file entirely.
-@end table
-
-Multiple @option{--exclude-tag*} options can be given.
-
-For example, given this directory:
-
-@smallexample
-@group
-$ @kbd{find dir}
-dir
-dir/blues
-dir/jazz
-dir/folk
-dir/folk/tagfile
-dir/folk/sanjuan
-dir/folk/trote
-@end group
-@end smallexample
-
-The @option{--exclude-tag} will produce the following:
-
-@smallexample
-$ @kbd{tar -cf archive.tar --exclude-tag=tagfile -v dir}
-dir/
-dir/blues
-dir/jazz
-dir/folk/
-tar: dir/folk/: contains a cache directory tag tagfile;
- contents not dumped
-dir/folk/tagfile
-@end smallexample
-
-Both the @file{dir/folk} directory and its tagfile are preserved in
-the archive, however the rest of files in this directory are not.
-
-Now, using the @option{--exclude-tag-under} option will exclude
-@file{tagfile} from the dump, while still preserving the directory
-itself, as shown in this example:
-
-@smallexample
-$ @kbd{tar -cf archive.tar --exclude-tag-under=tagfile -v dir}
-dir/
-dir/blues
-dir/jazz
-dir/folk/
-./tar: dir/folk/: contains a cache directory tag tagfile;
- contents not dumped
-@end smallexample
-
-Finally, using @option{--exclude-tag-all} omits the @file{dir/folk}
-directory entirely:
-
-@smallexample
-$ @kbd{tar -cf archive.tar --exclude-tag-all=tagfile -v dir}
-dir/
-dir/blues
-dir/jazz
-./tar: dir/folk/: contains a cache directory tag tagfile;
- directory not dumped
-@end smallexample
-
-@menu
-* problems with exclude::
-@end menu
-
-@node problems with exclude
-@unnumberedsubsec Problems with Using the @code{exclude} Options
-
-@xopindex{exclude, potential problems with}
-Some users find @samp{exclude} options confusing. Here are some common
-pitfalls:
-
-@itemize @bullet
-@item
-The main operating mode of @command{tar} does not act on a file 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.
-
-@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
-rather than:
-
-@smallexample
-# @emph{Wrong!}
-$ @kbd{tar -c -f @var{archive.tar} --exclude *.o @var{directory}}
-@end smallexample
-
-@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.
-
-@item
-@FIXME{The change in semantics must have occurred before 1.11,
-so I doubt if it is worth mentioning at all. Anyway, should at
-least specify in which version the semantics changed.}
-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.
-
-@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. @GNUTAR{} can use wildcard
-patterns for matching (or globbing) archive members when extracting
-from or listing an archive. 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: thus, excluding a directory also excludes all the files beneath it.
-
-@menu
-* controlling pattern-matching::
-@end menu
-
-@node controlling pattern-matching
-@unnumberedsubsec Controlling Pattern-Matching
-
-For the purposes of this section, we call @dfn{exclusion members} all
-member names obtained while processing @option{--exclude} and
-@option{--exclude-from} options, and @dfn{inclusion members} those
-member names that were given in the command line or read from the file
-specified with @option{--files-from} option.
-
-These two pairs of member lists are used in the following operations:
-@option{--diff}, @option{--extract}, @option{--list},
-@option{--update}.
-
-There are no inclusion members in create mode (@option{--create} and
-@option{--append}), since in this mode the names obtained from the
-command line refer to @emph{files}, not archive members.
-
-By default, inclusion members are compared with archive members
-literally @footnote{Notice that earlier @GNUTAR{} versions used
-globbing for inclusion members, which contradicted to UNIX98
-specification and was not documented. @xref{Changes}, for more
-information on this and other changes.} and exclusion members are
-treated as globbing patterns. For example:
-
-@smallexample
-@group
-$ @kbd{tar tf foo.tar}
-a.c
-b.c
-a.txt
-[remarks]
-# @i{Member names are used verbatim:}
-$ @kbd{tar -xf foo.tar -v '[remarks]'}
-[remarks]
-# @i{Exclude member names are globbed:}
-$ @kbd{tar -xf foo.tar -v --exclude '*.c'}
-a.txt
-[remarks]
-@end group
-@end smallexample
-
-This behavior can be altered by using the following options:
-
-@table @option
-@opindex wildcards
-@item --wildcards
-Treat all member names as wildcards.
-
-@opindex no-wildcards
-@item --no-wildcards
-Treat all member names as literal strings.
-@end table
-
-Thus, to extract files whose names end in @samp{.c}, you can use:
-
-@smallexample
-$ @kbd{tar -xf foo.tar -v --wildcards '*.c'}
-a.c
-b.c
-@end smallexample
-
-@noindent
-Notice quoting of the pattern to prevent the shell from interpreting
-it.
-
-The effect of @option{--wildcards} option is canceled by
-@option{--no-wildcards}. This can be used to pass part of
-the command line arguments verbatim and other part as globbing
-patterns. For example, the following invocation:
-
-@smallexample
-$ @kbd{tar -xf foo.tar --wildcards '*.txt' --no-wildcards '[remarks]'}
-@end smallexample
-
-@noindent
-instructs @command{tar} to extract from @file{foo.tar} all files whose
-names end in @samp{.txt} and the file named @file{[remarks]}.
-
-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
-
-@noindent
-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} for exclusion members
-and @option{--anchored} inclusion members.
-
-@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-match-slash
-@opindex no-wildcards-match-slash
-@item --wildcards-match-slash
-@itemx --no-wildcards-match-slash
-When wildcards match slash (the default for exclusion members), a
-wildcard like @samp{*} in the pattern can match a @samp{/} in the
-name. Otherwise, @samp{/} is matched only by @samp{/}.
-
-@end table
-
-The @option{--recursion} and @option{--no-recursion} options
-(@pxref{recurse}) also affect how member patterns are interpreted. If
-recursion is in effect, a pattern matches a name if it matches any of
-the name's parent directories.
-
-The following table summarizes pattern-matching default values:
-
-@multitable @columnfractions .3 .7
-@headitem Members @tab Default settings
-@item Inclusion @tab @option{--no-wildcards --anchored --no-wildcards-match-slash}
-@item Exclusion @tab @option{--wildcards --no-anchored --wildcards-match-slash}
-@end multitable
-
-@node quoting styles
-@section Quoting Member Names
-
-When displaying member names, @command{tar} takes care to avoid
-ambiguities caused by certain characters. This is called @dfn{name
-quoting}. The characters in question are:
-
-@itemize @bullet
-@item Non-printable control characters:
-@anchor{escape sequences}
-@multitable @columnfractions 0.20 0.10 0.60
-@headitem Character @tab @acronym{ASCII} @tab Character name
-@item \a @tab 7 @tab Audible bell
-@item \b @tab 8 @tab Backspace
-@item \f @tab 12 @tab Form feed
-@item \n @tab 10 @tab New line
-@item \r @tab 13 @tab Carriage return
-@item \t @tab 9 @tab Horizontal tabulation
-@item \v @tab 11 @tab Vertical tabulation
-@end multitable
-
-@item Space (@acronym{ASCII} 32)
-
-@item Single and double quotes (@samp{'} and @samp{"})
-
-@item Backslash (@samp{\})
-@end itemize
-
-The exact way @command{tar} uses to quote these characters depends on
-the @dfn{quoting style}. The default quoting style, called
-@dfn{escape} (see below), uses backslash notation to represent control
-characters, space and backslash. Using this quoting style, control
-characters are represented as listed in column @samp{Character} in the
-above table, a space is printed as @samp{\ } and a backslash as @samp{\\}.
-
-@GNUTAR{} offers seven distinct quoting styles, which can be selected
-using @option{--quoting-style} option:
-
-@table @option
-@item --quoting-style=@var{style}
-@opindex quoting-style
-
-Sets quoting style. Valid values for @var{style} argument are:
-literal, shell, shell-always, c, escape, locale, clocale.
-@end table
-
-These styles are described in detail below. To illustrate their
-effect, we will use an imaginary tar archive @file{arch.tar}
-containing the following members:
-
-@smallexample
-@group
-# 1. Contains horizontal tabulation character.
-a tab
-# 2. Contains newline character
-a
-newline
-# 3. Contains a space
-a space
-# 4. Contains double quotes
-a"double"quote
-# 5. Contains single quotes
-a'single'quote
-# 6. Contains a backslash character:
-a\backslash
-@end group
-@end smallexample
-
-Here is how usual @command{ls} command would have listed them, if they
-had existed in the current working directory:
-
-@smallexample
-@group
-$ @kbd{ls}
-a\ttab
-a\nnewline
-a\ space
-a"double"quote
-a'single'quote
-a\\backslash
-@end group
-@end smallexample
-
-Quoting styles:
-
-@table @samp
-@item literal
-No quoting, display each character as is:
-
-@smallexample
-@group
-$ @kbd{tar tf arch.tar --quoting-style=literal}
-./
-./a space
-./a'single'quote
-./a"double"quote
-./a\backslash
-./a tab
-./a
-newline
-@end group
-@end smallexample
-
-@item shell
-Display characters the same way Bourne shell does:
-control characters, except @samp{\t} and @samp{\n}, are printed using
-backslash escapes, @samp{\t} and @samp{\n} are printed as is, and a
-single quote is printed as @samp{\'}. If a name contains any quoted
-characters, it is enclosed in single quotes. In particular, if a name
-contains single quotes, it is printed as several single-quoted strings:
-
-@smallexample
-@group
-$ @kbd{tar tf arch.tar --quoting-style=shell}
-./
-'./a space'
-'./a'\''single'\''quote'
-'./a"double"quote'
-'./a\backslash'
-'./a tab'
-'./a
-newline'
-@end group
-@end smallexample
-
-@item shell-always
-Same as @samp{shell}, but the names are always enclosed in single
-quotes:
-
-@smallexample
-@group
-$ @kbd{tar tf arch.tar --quoting-style=shell-always}
-'./'
-'./a space'
-'./a'\''single'\''quote'
-'./a"double"quote'
-'./a\backslash'
-'./a tab'
-'./a
-newline'
-@end group
-@end smallexample
-
-@item c
-Use the notation of the C programming language. All names are
-enclosed in double quotes. Control characters are quoted using
-backslash notations, double quotes are represented as @samp{\"},
-backslash characters are represented as @samp{\\}. Single quotes and
-spaces are not quoted:
-
-@smallexample
-@group
-$ @kbd{tar tf arch.tar --quoting-style=c}
-"./"
-"./a space"
-"./a'single'quote"
-"./a\"double\"quote"
-"./a\\backslash"
-"./a\ttab"
-"./a\nnewline"
-@end group
-@end smallexample
-
-@item escape
-Control characters are printed using backslash notation, a space is
-printed as @samp{\ } and a backslash as @samp{\\}. This is the
-default quoting style, unless it was changed when configured the
-package.
-
-@smallexample
-@group
-$ @kbd{tar tf arch.tar --quoting-style=escape}
-./
-./a space
-./a'single'quote
-./a"double"quote
-./a\\backslash
-./a\ttab
-./a\nnewline
-@end group
-@end smallexample
-
-@item locale
-Control characters, single quote and backslash are printed using
-backslash notation. All names are quoted using left and right
-quotation marks, appropriate to the current locale. If it does not
-define quotation marks, use @samp{`} as left and @samp{'} as right
-quotation marks. Any occurrences of the right quotation mark in a
-name are escaped with @samp{\}, for example:
-
-For example:
-
-@smallexample
-@group
-$ @kbd{tar tf arch.tar --quoting-style=locale}
-`./'
-`./a space'
-`./a\'single\'quote'
-`./a"double"quote'
-`./a\\backslash'
-`./a\ttab'
-`./a\nnewline'
-@end group
-@end smallexample
-
-@item clocale
-Same as @samp{locale}, but @samp{"} is used for both left and right
-quotation marks, if not provided by the currently selected locale:
-
-@smallexample
-@group
-$ @kbd{tar tf arch.tar --quoting-style=clocale}
-"./"
-"./a space"
-"./a'single'quote"
-"./a\"double\"quote"
-"./a\\backslash"
-"./a\ttab"
-"./a\nnewline"
-@end group
-@end smallexample
-@end table
-
-You can specify which characters should be quoted in addition to those
-implied by the current quoting style:
-
-@table @option
-@item --quote-chars=@var{string}
-Always quote characters from @var{string}, even if the selected
-quoting style would not quote them.
-@end table
-
-For example, using @samp{escape} quoting (compare with the usual
-escape listing above):
-
-@smallexample
-@group
-$ @kbd{tar tf arch.tar --quoting-style=escape --quote-chars=' "'}
-./
-./a\ space
-./a'single'quote
-./a\"double\"quote
-./a\\backslash
-./a\ttab
-./a\nnewline
-@end group
-@end smallexample
-
-To disable quoting of such additional characters, use the following
-option:
-
-@table @option
-@item --no-quote-chars=@var{string}
-Remove characters listed in @var{string} from the list of quoted
-characters set by the previous @option{--quote-chars} option.
-@end table
-
-This option is particularly useful if you have added
-@option{--quote-chars} to your @env{TAR_OPTIONS} (@pxref{TAR_OPTIONS})
-and wish to disable it for the current invocation.
-
-Note, that @option{--no-quote-chars} does @emph{not} disable those
-characters that are quoted by default in the selected quoting style.
-
-@node transform
-@section Modifying File and Member Names
-
-@command{Tar} archives contain detailed information about files stored
-in them and full file names are part of that information. When
-storing file to an archive, its file name is recorded in the archive
-along with the actual file contents. When restoring from an archive,
-a file is created on disk with exactly the same name as that stored
-in the archive. In the majority of cases this is the desired behavior
-of a file archiver. However, there are some cases when it is not.
-
-First of all, it is often unsafe to extract archive members with
-absolute file names or those that begin with a @file{../}. @GNUTAR{}
-takes special precautions when extracting such names and provides a
-special option for handling them, which is described in
-@ref{absolute}.
-
-Secondly, you may wish to extract file names without some leading
-directory components, or with otherwise modified names. In other
-cases it is desirable to store files under differing names in the
-archive.
-
-@GNUTAR{} provides two options for these needs.
-
-@table @option
-@opindex strip-components
-@item --strip-components=@var{number}
-Strip given @var{number} of leading components from file names before
-extraction.
-@end table
-
-For example, suppose you have archived whole @file{/usr} hierarchy to
-a tar archive named @file{usr.tar}. Among other files, this archive
-contains @file{usr/include/stdlib.h}, which you wish to extract to
-the current working directory. To do so, you type:
-
-@smallexample
-$ @kbd{tar -xf usr.tar --strip=2 usr/include/stdlib.h}
-@end smallexample
-
-The option @option{--strip=2} instructs @command{tar} to strip the
-two leading components (@file{usr/} and @file{include/}) off the file
-name.
-
-If you add to the above invocation @option{--verbose} (@option{-v})
-option, you will note that the verbose listing still contains the
-full file name, with the two removed components still in place. This
-can be inconvenient, so @command{tar} provides a special option for
-altering this behavior:
-
-@anchor{show-transformed-names}
-@table @option
-@opindex show-transformed-names
-@item --show-transformed-names
-Display file or member names with all requested transformations
-applied.
-@end table
-
-@noindent
-For example:
-
-@smallexample
-@group
-$ @kbd{tar -xf usr.tar -v --strip=2 usr/include/stdlib.h}
-usr/include/stdlib.h
-$ @kbd{tar -xf usr.tar -v --strip=2 --show-transformed usr/include/stdlib.h}
-stdlib.h
-@end group
-@end smallexample
-
-Notice that in both cases the file is @file{stdlib.h} extracted to the
-current working directory, @option{--show-transformed-names} affects
-only the way its name is displayed.
-
-This option is especially useful for verifying whether the invocation
-will have the desired effect. Thus, before running
-
-@smallexample
-$ @kbd{tar -x --strip=@var{n}}
-@end smallexample
-
-@noindent
-it is often advisable to run
-
-@smallexample
-$ @kbd{tar -t -v --show-transformed --strip=@var{n}}
-@end smallexample
-
-@noindent
-to make sure the command will produce the intended results.
-
-In case you need to apply more complex modifications to the file name,
-@GNUTAR{} provides a general-purpose transformation option:
-
-@table @option
-@opindex transform
-@item --transform=@var{expression}
-Modify file names using supplied @var{expression}.
-@end table
-
-@noindent
-The @var{expression} is a @command{sed}-like replace expression of the
-form:
-
-@smallexample
-s/@var{regexp}/@var{replace}/[@var{flags}]
-@end smallexample
-
-@noindent
-where @var{regexp} is a @dfn{regular expression}, @var{replace} is a
-replacement for each file name part that matches @var{regexp}. Both
-@var{regexp} and @var{replace} are described in detail in
-@ref{The "s" Command, The "s" Command, The `s' Command, sed, GNU sed}.
-
-As in @command{sed}, you can give several replace expressions,
-separated by a semicolon.
-
-Supported @var{flags} are:
-
-@table @samp
-@item g
-Apply the replacement to @emph{all} matches to the @var{regexp}, not
-just the first.
-
-@item i
-Use case-insensitive matching
-
-@item x
-@var{regexp} is an @dfn{extended regular expression} (@pxref{Extended
-regexps, Extended regular expressions, Extended regular expressions,
-sed, GNU sed}).
-
-@item @var{number}
-Only replace the @var{number}th match of the @var{regexp}.
-
-Note: the @var{posix} standard does not specify what should happen
-when you mix the @samp{g} and @var{number} modifiers. @GNUTAR{}
-follows the GNU @command{sed} implementation in this regard, so
-the interaction is defined to be: ignore matches before the
-@var{number}th, and then match and replace all matches from the
-@var{number}th on.
-
-@end table
-
-Any delimiter can be used in lieue of @samp{/}, the only requirement being
-that it be used consistently throughout the expression. For example,
-the following two expressions are equivalent:
-
-@smallexample
-@group
-s/one/two/
-s,one,two,
-@end group
-@end smallexample
-
-Changing delimiters is often useful when the @var{regex} contains
-slashes. For example, it is more convenient to write @code{s,/,-,} than
-@code{s/\//-/}.
-
-Here are several examples of @option{--transform} usage:
-
-@enumerate
-@item Extract @file{usr/} hierarchy into @file{usr/local/}:
-
-@smallexample
-$ @kbd{tar --transform='s,usr/,usr/local/,' -x -f arch.tar}
-@end smallexample
-
-@item Strip two leading directory components (equivalent to
-@option{--strip-components=2}):
-
-@smallexample
-$ @kbd{tar --transform='s,/*[^/]*/[^/]*/,,' -x -f arch.tar}
-@end smallexample
-
-@item Prepend @file{/prefix/} to each file name:
-
-@smallexample
-$ @kbd{tar --transform 's,^,/prefix/,' -x -f arch.tar}
-@end smallexample
-
-@item Convert each file name to lower case:
-
-@smallexample
-$ @kbd{tar --transform 's/.*/\L&/' -x -f arch.tar}
-@end smallexample
-
-@end enumerate
-
-Unlike @option{--strip-components}, @option{--transform} can be used
-in any @GNUTAR{} operation mode. For example, the following command
-adds files to the archive while replacing the leading @file{usr/}
-component with @file{var/}:
-
-@smallexample
-$ @kbd{tar -cf arch.tar --transform='s,^usr/,var/,' /}
-@end smallexample
-
-To test @option{--transform} effect we suggest using
-@option{--show-transformed-names} option:
-
-@smallexample
-$ @kbd{tar -cf arch.tar --transform='s,^usr/,var/,' \
- --verbose --show-transformed-names /}
-@end smallexample
-
-If both @option{--strip-components} and @option{--transform} are used
-together, then @option{--transform} is applied first, and the required
-number of components is then stripped from its result.
-
-You can use as many @option{--transform} options in a single command
-line as you want. The specified expressions will then be applied in
-order of their appearance. For example, the following two invocations
-are equivalent:
-
-@smallexample
-$ @kbd{tar -cf arch.tar --transform='s,/usr/var,/var/' \
- --transform='s,/usr/local,/usr/,'}
-$ @kbd{tar -cf arch.tar \
- --transform='s,/usr/var,/var/;s,/usr/local,/usr/,'}
-@end smallexample
-
-@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
-
-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.)
-
-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.
-
-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).
-
-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. For example, the following command will add to the archive
-all the files modified less than two days ago:
-
-@smallexample
-$ @kbd{tar -cf foo.tar --newer-mtime '2 days ago'}
-@end smallexample
-
-When any of these options is used with the option @option{--verbose}
-(@pxref{verbose tutorial}) @GNUTAR{} will try to convert the specified
-date back to its textual representation and compare that with the
-one given with the option. If the two dates differ, @command{tar} will
-print a warning saying what date it will use. This is to help user
-ensure he is using the right date. For example:
-
-@smallexample
-@group
-$ @kbd{tar -c -f archive.tar --after-date='10 days ago' .}
-tar: Option --after-date: Treating date `10 days ago' as 2006-06-11
-13:19:37.232434
-@end group
-@end smallexample
-
-@quotation
-@strong{Please Note:} @option{--after-date} and @option{--newer-mtime}
-should not be used for incremental backups. @xref{Incremental Dumps},
-for proper way of creating incremental backups.
-@end quotation
-
-@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. :-< }
-
-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{-not -type d}}
-test in their @command{find} invocation (@pxref{Type, Type, Type test,
-find, Finding Files}), 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. To summarize, if you use @command{find} to
-create a list of files to be stored in an archive, use it as follows:
-
-@smallexample
-@group
-$ @kbd{find @var{dir} @var{tests} | \
- tar -cf @var{archive} -T - --no-recursion}
-@end group
-@end smallexample
-
-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 globbing patterns
-are interpreted (@pxref{controlling pattern-matching}).
-
-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
-
-@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}. 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
-Prevents @command{tar} from crossing file system boundaries when
-archiving. Use in conjunction with any write operation.
-@end table
-
-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.
-
-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.
-
-@menu
-* directory:: Changing Directory
-* absolute:: Absolute File Names
-@end menu
-
-@node directory
-@subsection Changing the Working Directory
-
-@FIXME{need to read over this node now for continuity; i've switched
-things around some.}
-
-@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
-
-For example,
-
-@smallexample
-$ @kbd{tar -c -f jams.tar grape prune -C food cherry}
-@end smallexample
-
-@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.
-
-Contrast this with the command,
-
-@smallexample
-$ @kbd{tar -c -f jams.tar grape prune -C food red/cherry}
-@end smallexample
-
-@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}.
-
-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}:
-
-@smallexample
-$ @kbd{tar -c -f foo.tar -C /etc passwd hosts -C /lib libc.a}
-@end smallexample
-
-@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
---directory=/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
-
-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)}
-# @i{or}:
-$ @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 file names 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 @acronym{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 file names 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 file name can be split at a 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 accommodate
-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 file name 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{}.
-
-@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 File 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
-* Compression:: Using Less Space through Compression
-* Attributes:: Handling File Attributes
-* Portability:: Making @command{tar} Archives More Portable
-* cpio:: Comparison of @command{tar} and @command{cpio}
-@end menu
-
-@node Compression
-@section Using Less Space through Compression
-
-@menu
-* gzip:: Creating and Reading Compressed Archives
-* sparse:: Archiving Sparse Files
-@end menu
-
-@node gzip
-@subsection Creating and Reading Compressed Archives
-@cindex Compressed archives
-@cindex Storing archives in compressed format
-
-@GNUTAR{} is able to create and read compressed archives. It supports
-@command{gzip}, @command{bzip2} and @command{lzma} compression
-programs. For backward compatibility, it also supports
-@command{compress} command, although we strongly recommend against
-using it, because it is by far less effective than other compression
-programs@footnote{It also had patent problems in the past.}.
-
-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,
-@option{--lzma} to create an @asis{LZMA} compressed archive and
-@option{-Z} (@option{--compress}) to use @command{compress} program.
-For example:
-
-@smallexample
-$ @kbd{tar cfz archive.tar.gz .}
-@end smallexample
-
-You can also let @GNUTAR{} select the compression program basing on
-the suffix of the archive file name. This is done using
-@option{--auto-compress} (@option{-a}) command line option. For
-example, the following invocation will use @command{bzip2} for
-compression:
-
-@smallexample
-$ @kbd{tar cfa archive.tar.bz2 .}
-@end smallexample
-
-@noindent
-whereas the following one will use @command{lzma}:
-
-@smallexample
-$ @kbd{tar cfa archive.tar.lzma .}
-@end smallexample
-
-For a complete list of file name suffixes recognized by @GNUTAR{},
-@ref{auto-compress}.
-
-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 or
-add (@option{--append} (@option{-r})) members to them. Likewise, you
-cannot append another @command{tar} archive to a compressed archive using
-@option{--concatenate} (@option{-A})). Secondly, multi-volume
-archives cannot be compressed.
-
-The following table summarizes compression options used by @GNUTAR{}.
-
-@table @option
-@anchor{auto-compress}
-@opindex auto-compress
-@item --auto-compress
-@itemx -a
-Select a compression program to use by the archive file name
-suffix. The following suffixes are recognized:
-
-@multitable @columnfractions 0.3 0.6
-@headitem Suffix @tab Compression program
-@item @samp{.gz} @tab @command{gzip}
-@item @samp{.tgz} @tab @command{gzip}
-@item @samp{.taz} @tab @command{gzip}
-@item @samp{.Z} @tab @command{compress}
-@item @samp{.taZ} @tab @command{compress}
-@item @samp{.bz2} @tab @command{bzip2}
-@item @samp{.tz2} @tab @command{bzip2}
-@item @samp{.tbz2} @tab @command{bzip2}
-@item @samp{.tbz} @tab @command{bzip2}
-@item @samp{.lzma} @tab @command{lzma}
-@item @samp{.tlz} @tab @command{lzma}
-@end multitable
-
-@opindex gzip
-@opindex ungzip
-@item -z
-@itemx --gzip
-@itemx --ungzip
-Filter the archive through @command{gzip}.
-
-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.:
-
-@smallexample
-$ @kbd{GZIP=--best tar cfz archive.tar.gz subdir}
-@end smallexample
-
-@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 lzma
-@item --lzma
-Filter the archive through @command{lzma}. Otherwise like @option{--gzip}.
-
-@opindex compress
-@opindex uncompress
-@item -Z
-@itemx --compress
-@itemx --uncompress
-Filter the archive through @command{compress}. Otherwise like @option{--gzip}.
-
-@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
-
-@cindex gpg, using with tar
-@cindex gnupg, using with tar
-@cindex Using encrypted archives
-The @option{--use-compress-program} option, in particular, lets you
-implement your own filters, not necessarily dealing with
-compression/decompression. For example, suppose you wish to implement
-PGP encryption on top of compression, using @command{gpg} (@pxref{Top,
-gpg, gpg ---- encryption and signing tool, gpg, GNU Privacy Guard
-Manual}). The following script does that:
-
-@smallexample
-@group
-#! /bin/sh
-case $1 in
--d) gpg --decrypt - | gzip -d -c;;
-'') gzip -c | gpg -s ;;
-*) echo "Unknown option $1">&2; exit 1;;
-esac
-@end group
-@end smallexample
-
-Suppose you name it @file{gpgz} and save it somewhere in your
-@env{PATH}. Then the following command will create a compressed
-archive signed with your private key:
-
-@smallexample
-$ @kbd{tar -cf foo.tar.gpgz --use-compress=gpgz .}
-@end smallexample
-
-@noindent
-Likewise, the following command will list its contents:
-
-@smallexample
-$ @kbd{tar -tf foo.tar.gpgz --use-compress=gpgz .}
-@end smallexample
-
-@ignore
-The above is based on the following discussion:
-
- 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.
-@end ignore
-
-@node sparse
-@subsection Archiving Sparse Files
-@cindex Sparse Files
-
-Files in the file system occasionally have @dfn{holes}. A @dfn{hole}
-in a file is a section of the file's contents which was never written.
-The contents of a hole reads 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.
-
-@table @option
-@opindex sparse
-@item -S
-@itemx --sparse
-This option instructs @command{tar} to test each file for sparseness
-before attempting to archive it. If the file is found to be sparse it
-is treated specially, thus allowing to decrease the amount of space
-used by its image in the archive.
-
-This option is meaningful only when creating or updating archives. It
-has no effect on extraction.
-@end table
-
-Consider using @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). @xref{Incremental Dumps}.
-
-However, be aware that @option{--sparse} option presents a serious
-drawback. Namely, in order to determine if the file is sparse
-@command{tar} has to read it before trying to archive it, so in total
-the file is read @strong{twice}. So, always bear in mind that the
-time needed to process all files with this option is roughly twice
-the time needed to archive them without it.
-@FIXME{A technical note:
-
-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
-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
-}
-
-@cindex sparse formats, defined
-When using @samp{POSIX} archive format, @GNUTAR{} is able to store
-sparse files using in three distinct ways, called @dfn{sparse
-formats}. A sparse format is identified by its @dfn{number},
-consisting, as usual of two decimal numbers, delimited by a dot. By
-default, format @samp{1.0} is used. If, for some reason, you wish to
-use an earlier format, you can select it using
-@option{--sparse-version} option.
-
-@table @option
-@opindex sparse-version
-@item --sparse-version=@var{version}
-
-Select the format to store sparse files in. Valid @var{version} values
-are: @samp{0.0}, @samp{0.1} and @samp{1.0}. @xref{Sparse Formats},
-for a detailed description of each format.
-@end table
-
-Using @option{--sparse-format} option implies @option{--sparse}.
-
-@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{Incremental Dumps}), 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.
-
-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.
-
-This option is meaningless with @option{--list} (@option{-t}).
-
-@opindex same-owner
-@item --same-owner
-Create extracted files with the same ownership they have in the
-archive.
-
-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 @acronym{ID} and user name
-separately. If it can't find a user name (because the user @acronym{ID} is not
-in @file{/etc/passwd}), then it does not write one. When restoring,
-it tries to look the name (if one was written) up in
-@file{/etc/passwd}. If it fails, then it uses the user @acronym{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.
-
-@xopindex{same-permissions, short description}
-@xopindex{preserve-permissions, short description}
-@item -p
-@itemx --same-permissions
-@itemx --preserve-permissions
-Extract all protection information.
-
-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.
-
-
-This option is meaningless with @option{--list} (@option{-t}).
-
-@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}.
-
-@FIXME{I do not see the purpose of such an option. (Neither I. FP.)
-Neither do I. --Sergey}
-
-@end table
-
-@node Portability
-@section Making @command{tar} Archives More Portable
-
-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.
-
-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.
-
-@FIXME{Discuss GNU extensions (incremental backups, multi-volume
-archives and archive labels) in GNU and PAX formats.}
-
-@menu
-* Portable Names:: Portable Names
-* dereference:: Symbolic Links
-* hard links:: Hard 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.
-* Other Tars:: How to Extract GNU-Specific Data Using
- Other @command{tar} Implementations
-@end menu
-
-@node Portable Names
-@subsection Portable Names
-
-Use portable file and member names. A name is portable if it contains
-only @acronym{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
-
-@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.
-
-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.
-
-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.)
-
-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.
-
-@node hard links
-@subsection Hard Links
-@UNREVISED{}
-@cindex File names, using hard links
-@cindex hard links, dereferencing
-@cindex dereferencing hard links
-
-Normally, when @command{tar} archives a hard link, it writes a
-block to the archive naming the target of the link (a @samp{1} type
-block). In that way, the actual file contents is stored in file only
-once. For example, consider the following two files:
-
-@smallexample
-@group
-$ ls
--rw-r--r-- 2 gray staff 4 2007-10-30 15:11 one
--rw-r--r-- 2 gray staff 4 2007-10-30 15:11 jeden
-@end group
-@end smallexample
-
-Here, @file{jeden} is a link to @file{one}. When archiving this
-directory with a verbose level 2, you will get an output similar to
-the following:
-
-@smallexample
-$ tar cfvv ../archive.tar .
-drwxr-xr-x gray/staff 0 2007-10-30 15:13 ./
--rw-r--r-- gray/staff 4 2007-10-30 15:11 ./jeden
-hrw-r--r-- gray/staff 0 2007-10-30 15:11 ./one link to ./jeden
-@end smallexample
-
-The last line shows that, instead of storing two copies of the file,
-@command{tar} stored it only once, under the name @file{jeden}, and
-stored file @file{one} as a hard link to this file.
-
-It may be important to know that all hard links to the given file are
-stored in the archive. For example, this may be necessary for exact
-reproduction of the file system. The following option does that:
-
-@table @option
-@xopindex{check-links, described}
-@item --check-links
-@itemx -l
-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, print
-a warning message.
-@end table
-
-For example, trying to archive only file @file{jeden} with this option
-produces the following diagnostics:
-
-@smallexample
-$ tar -c -f ../archive.tar jeden
-tar: Missing links to `jeden'.
-@end smallexample
-
-Although creating special records for hard links helps keep a faithful
-record of the file system contents and makes archives more compact, it
-may present some difficulties when extracting individual members from
-the archive. For example, trying to extract file @file{one} from the
-archive created in previous examples produces, in the absense of file
-@file{jeden}:
-
-@smallexample
-$ tar xf archive.tar ./one
-tar: ./one: Cannot hard link to `./jeden': No such file or directory
-tar: Error exit delayed from previous errors
-@end smallexample
-
-The reason for this behavior is that @command{tar} cannot seek back in
-the archive to the previous member (in this case, @file{one}), to
-extract it@footnote{There are plans to fix this in future releases.}.
-If you wish to avoid such problems at the cost of a bigger archive,
-use the following option:
-
-@table @option
-@xopindex{hard-dereference, described}
-@item --hard-dereference
-Dereference hard links and store the files they refer to.
-@end table
-
-For example, trying this option on our two sample files, we get two
-copies in the archive, each of which can then be extracted
-independently of the other:
-
-@smallexample
-@group
-$ tar -c -vv -f ../archive.tar --hard-dereference .
-drwxr-xr-x gray/staff 0 2007-10-30 15:13 ./
--rw-r--r-- gray/staff 4 2007-10-30 15:11 ./jeden
--rw-r--r-- gray/staff 4 2007-10-30 15:11 ./one
-@end group
-@end smallexample
-
-@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 @option{--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. Notice,
-however, that @samp{ustar} format is a better alternative, as it is
-free from many of @samp{v7}'s drawbacks.
-
-@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 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
-Starting from version 1.14 @GNUTAR{} features full support for
-@acronym{POSIX.1-2001} archives.
-
-A @acronym{POSIX} conformant archive will be created if @command{tar}
-was given @option{--format=posix} (@option{--format=pax}) option. No
-special option is required to read and extract from a @acronym{POSIX}
-archive.
-
-@menu
-* PAX keywords:: Controlling Extended Header Keywords.
-@end menu
-
-@node PAX keywords
-@subsubsection Controlling Extended Header Keywords
-
-@table @option
-@opindex pax-option
-@item --pax-option=@var{keyword-list}
-Handle keywords in @acronym{PAX} extended headers. This option is
-equivalent to @option{-o} option of the @command{pax} utility.
-@end table
-
-@var{Keyword-list} is a comma-separated
-list of keyword options, each keyword option taking one of
-the following forms:
-
-@table @code
-@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
-(@pxref{wildcards}). 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 making the following substitutions:
-
-@multitable @columnfractions .25 .55
-@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 file name.
-@item %f @tab The name of the file with the directory information
-stripped, equivalent to the result of the @command{basename} utility
-on the translated file name.
-@item %p @tab The process @acronym{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
-is obtained from the contents of @var{string}, after making
-the following substitutions:
-
-@multitable @columnfractions .25 .55
-@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 @acronym{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{globexthdr.name=string} is specified, @command{tar}
-will use the following default value:
-
-@smallexample
-$TMPDIR/GlobalHead.%p.%n
-@end smallexample
-
-@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
-
-@node Checksumming
-@subsection Checksumming Problems
-
-SunOS and HP-UX @command{tar} fail to accept archives created using
-@GNUTAR{} and containing non-@acronym{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 Other Tars
-@subsection How to Extract GNU-Specific Data Using Other @command{tar} Implementations
-
-In previous sections you became acquainted with various quirks
-necessary to make your archives portable. Sometimes you may need to
-extract archives containing GNU-specific members using some
-third-party @command{tar} implementation or an older version of
-@GNUTAR{}. Of course your best bet is to have @GNUTAR{} installed,
-but if it is for some reason impossible, this section will explain
-how to cope without it.
-
-When we speak about @dfn{GNU-specific} members we mean two classes of
-them: members split between the volumes of a multi-volume archive and
-sparse members. You will be able to always recover such members if
-the archive is in PAX format. In addition split members can be
-recovered from archives in old GNU format. The following subsections
-describe the required procedures in detail.
-
-@menu
-* Split Recovery:: Members Split Between Volumes
-* Sparse Recovery:: Sparse Members
-@end menu
-
-@node Split Recovery
-@subsubsection Extracting Members Split Between Volumes
-
-@cindex Mutli-volume archives, extracting using non-GNU tars
-If a member is split between several volumes of an old GNU format archive
-most third party @command{tar} implementation will fail to extract
-it. To extract it, use @command{tarcat} program (@pxref{Tarcat}).
-This program is available from
-@uref{http://www.gnu.org/@/software/@/tar/@/utils/@/tarcat.html, @GNUTAR{}
-home page}. It concatenates several archive volumes into a single
-valid archive. For example, if you have three volumes named from
-@file{vol-1.tar} to @file{vol-3.tar}, you can do the following to
-extract them using a third-party @command{tar}:
-
-@smallexample
-$ @kbd{tarcat vol-1.tar vol-2.tar vol-3.tar | tar xf -}
-@end smallexample
-
-@cindex Mutli-volume archives in PAX format, extracting using non-GNU tars
-You could use this approach for most (although not all) PAX
-format archives as well. However, extracting split members from a PAX
-archive is a much easier task, because PAX volumes are constructed in
-such a way that each part of a split member is extracted to a
-different file by @command{tar} implementations that are not aware of
-GNU extensions. More specifically, the very first part retains its
-original name, and all subsequent parts are named using the pattern:
-
-@smallexample
-%d/GNUFileParts.%p/%f.%n
-@end smallexample
-
-@noindent
-where symbols preceeded by @samp{%} are @dfn{macro characters} that
-have the following meaning:
-
-@multitable @columnfractions .25 .55
-@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 its full name.
-@item %f @tab The file name of the file, equivalent to the result
-of the @command{basename} utility on its full name.
-@item %p @tab The process @acronym{ID} of the @command{tar} process that
-created the archive.
-@item %n @tab Ordinal number of this particular part.
-@end multitable
-
-For example, if the file @file{var/longfile} was split during archive
-creation between three volumes, and the creator @command{tar} process
-had process @acronym{ID} @samp{27962}, then the member names will be:
-
-@smallexample
-var/longfile
-var/GNUFileParts.27962/longfile.1
-var/GNUFileParts.27962/longfile.2
-@end smallexample
-
-When you extract your archive using a third-party @command{tar}, these
-files will be created on your disk, and the only thing you will need
-to do to restore your file in its original form is concatenate them in
-the proper order, for example:
-
-@smallexample
-@group
-$ @kbd{cd var}
-$ @kbd{cat GNUFileParts.27962/longfile.1 \
- GNUFileParts.27962/longfile.2 >> longfile}
-$ rm -f GNUFileParts.27962
-@end group
-@end smallexample
-
-Notice, that if the @command{tar} implementation you use supports PAX
-format archives, it will probably emit warnings about unknown keywords
-during extraction. They will look like this:
-
-@smallexample
-@group
-Tar file too small
-Unknown extended header keyword 'GNU.volume.filename' ignored.
-Unknown extended header keyword 'GNU.volume.size' ignored.
-Unknown extended header keyword 'GNU.volume.offset' ignored.
-@end group
-@end smallexample
-
-@noindent
-You can safely ignore these warnings.
-
-If your @command{tar} implementation is not PAX-aware, you will get
-more warnings and more files generated on your disk, e.g.:
-
-@smallexample
-@group
-$ @kbd{tar xf vol-1.tar}
-var/PaxHeaders.27962/longfile: Unknown file type 'x', extracted as
-normal file
-Unexpected EOF in archive
-$ @kbd{tar xf vol-2.tar}
-tmp/GlobalHead.27962.1: Unknown file type 'g', extracted as normal file
-GNUFileParts.27962/PaxHeaders.27962/sparsefile.1: Unknown file type
-'x', extracted as normal file
-@end group
-@end smallexample
-
-Ignore these warnings. The @file{PaxHeaders.*} directories created
-will contain files with @dfn{extended header keywords} describing the
-extracted files. You can delete them, unless they describe sparse
-members. Read further to learn more about them.
-
-@node Sparse Recovery
-@subsubsection Extracting Sparse Members
-
-@cindex sparse files, extracting with non-GNU tars
-Any @command{tar} implementation will be able to extract sparse members from a
-PAX archive. However, the extracted files will be @dfn{condensed},
-i.e., any zero blocks will be removed from them. When we restore such
-a condensed file to its original form, by adding zero blocks (or
-@dfn{holes}) back to their original locations, we call this process
-@dfn{expanding} a compressed sparse file.
-
-@pindex xsparse
-To expand a file, you will need a simple auxiliary program called
-@command{xsparse}. It is available in source form from
-@uref{http://www.gnu.org/@/software/@/tar/@/utils/@/xsparse.html, @GNUTAR{}
-home page}.
-
-@cindex sparse files v.1.0, extracting with non-GNU tars
-Let's begin with archive members in @dfn{sparse format
-version 1.0}@footnote{@xref{PAX 1}.}, which are the easiest to expand.
-The condensed file will contain both file map and file data, so no
-additional data will be needed to restore it. If the original file
-name was @file{@var{dir}/@var{name}}, then the condensed file will be
-named @file{@var{dir}/@/GNUSparseFile.@var{n}/@/@var{name}}, where
-@var{n} is a decimal number@footnote{technically speaking, @var{n} is a
-@dfn{process @acronym{ID}} of the @command{tar} process which created the
-archive (@pxref{PAX keywords}).}.
-
-To expand a version 1.0 file, run @command{xsparse} as follows:
-
-@smallexample
-$ @kbd{xsparse @file{cond-file}}
-@end smallexample
-
-@noindent
-where @file{cond-file} is the name of the condensed file. The utility
-will deduce the name for the resulting expanded file using the
-following algorithm:
-
-@enumerate 1
-@item If @file{cond-file} does not contain any directories,
-@file{../cond-file} will be used;
-
-@item If @file{cond-file} has the form
-@file{@var{dir}/@var{t}/@var{name}}, where both @var{t} and @var{name}
-are simple names, with no @samp{/} characters in them, the output file
-name will be @file{@var{dir}/@var{name}}.
-
-@item Otherwise, if @file{cond-file} has the form
-@file{@var{dir}/@var{name}}, the output file name will be
-@file{@var{name}}.
-@end enumerate
-
-In the unlikely case when this algorithm does not suit your needs,
-you can explicitly specify output file name as a second argument to
-the command:
-
-@smallexample
-$ @kbd{xsparse @file{cond-file} @file{out-file}}
-@end smallexample
-
-It is often a good idea to run @command{xsparse} in @dfn{dry run} mode
-first. In this mode, the command does not actually expand the file,
-but verbosely lists all actions it would be taking to do so. The dry
-run mode is enabled by @option{-n} command line argument:
-
-@smallexample
-@group
-$ @kbd{xsparse -n /home/gray/GNUSparseFile.6058/sparsefile}
-Reading v.1.0 sparse map
-Expanding file `/home/gray/GNUSparseFile.6058/sparsefile' to
-`/home/gray/sparsefile'
-Finished dry run
-@end group
-@end smallexample
-
-To actually expand the file, you would run:
-
-@smallexample
-$ @kbd{xsparse /home/gray/GNUSparseFile.6058/sparsefile}
-@end smallexample
-
-@noindent
-The program behaves the same way all UNIX utilities do: it will keep
-quiet unless it has simething important to tell you (e.g. an error
-condition or something). If you wish it to produce verbose output,
-similar to that from the dry run mode, use @option{-v} option:
-
-@smallexample
-@group
-$ @kbd{xsparse -v /home/gray/GNUSparseFile.6058/sparsefile}
-Reading v.1.0 sparse map
-Expanding file `/home/gray/GNUSparseFile.6058/sparsefile' to
-`/home/gray/sparsefile'
-Done
-@end group
-@end smallexample
-
-Additionally, if your @command{tar} implementation has extracted the
-@dfn{extended headers} for this file, you can instruct @command{xstar}
-to use them in order to verify the integrity of the expanded file.
-The option @option{-x} sets the name of the extended header file to
-use. Continuing our example:
-
-@smallexample
-@group
-$ @kbd{xsparse -v -x /home/gray/PaxHeaders.6058/sparsefile \
- /home/gray/GNUSparseFile.6058/sparsefile}
-Reading extended header file
-Found variable GNU.sparse.major = 1
-Found variable GNU.sparse.minor = 0
-Found variable GNU.sparse.name = sparsefile
-Found variable GNU.sparse.realsize = 217481216
-Reading v.1.0 sparse map
-Expanding file `/home/gray/GNUSparseFile.6058/sparsefile' to
-`/home/gray/sparsefile'
-Done
-@end group
-@end smallexample
-
-@anchor{extracting sparse v.0.x}
-@cindex sparse files v.0.1, extracting with non-GNU tars
-@cindex sparse files v.0.0, extracting with non-GNU tars
-An @dfn{extended header} is a special @command{tar} archive header
-that precedes an archive member and contains a set of
-@dfn{variables}, describing the member properties that cannot be
-stored in the standard @code{ustar} header. While optional for
-expanding sparse version 1.0 members, the use of extended headers is
-mandatory when expanding sparse members in older sparse formats: v.0.0
-and v.0.1 (The sparse formats are described in detail in @ref{Sparse
-Formats}.) So, for these formats, the question is: how to obtain
-extended headers from the archive?
-
-If you use a @command{tar} implementation that does not support PAX
-format, extended headers for each member will be extracted as a
-separate file. If we represent the member name as
-@file{@var{dir}/@var{name}}, then the extended header file will be
-named @file{@var{dir}/@/PaxHeaders.@var{n}/@/@var{name}}, where
-@var{n} is an integer number.
-
-Things become more difficult if your @command{tar} implementation
-does support PAX headers, because in this case you will have to
-manually extract the headers. We recommend the following algorithm:
-
-@enumerate 1
-@item
-Consult the documentation of your @command{tar} implementation for an
-option that prints @dfn{block numbers} along with the archive
-listing (analogous to @GNUTAR{}'s @option{-R} option). For example,
-@command{star} has @option{-block-number}.
-
-@item
-Obtain verbose listing using the @samp{block number} option, and
-find block numbers of the sparse member in question and the member
-immediately following it. For example, running @command{star} on our
-archive we obtain:
-
-@smallexample
-@group
-$ @kbd{star -t -v -block-number -f arc.tar}
-@dots{}
-star: Unknown extended header keyword 'GNU.sparse.size' ignored.
-star: Unknown extended header keyword 'GNU.sparse.numblocks' ignored.
-star: Unknown extended header keyword 'GNU.sparse.name' ignored.
-star: Unknown extended header keyword 'GNU.sparse.map' ignored.
-block 56: 425984 -rw-r--r-- gray/users Jun 25 14:46 2006 GNUSparseFile.28124/sparsefile
-block 897: 65391 -rw-r--r-- gray/users Jun 24 20:06 2006 README
-@dots{}
-@end group
-@end smallexample
-
-@noindent
-(as usual, ignore the warnings about unknown keywords.)
-
-@item
-Let @var{size} be the size of the sparse member, @var{Bs} be its block number
-and @var{Bn} be the block number of the next member.
-Compute:
-
-@smallexample
-@var{N} = @var{Bs} - @var{Bn} - @var{size}/512 - 2
-@end smallexample
-
-@noindent
-This number gives the size of the extended header part in tar @dfn{blocks}.
-In our example, this formula gives: @code{897 - 56 - 425984 / 512 - 2
-= 7}.
-
-@item
-Use @command{dd} to extract the headers:
-
-@smallexample
-@kbd{dd if=@var{archive} of=@var{hname} bs=512 skip=@var{Bs} count=@var{N}}
-@end smallexample
-
-@noindent
-where @var{archive} is the archive name, @var{hname} is a name of the
-file to store the extended header in, @var{Bs} and @var{N} are
-computed in previous steps.
-
-In our example, this command will be
-
-@smallexample
-$ @kbd{dd if=arc.tar of=xhdr bs=512 skip=56 count=7}
-@end smallexample
-@end enumerate
-
-Finally, you can expand the condensed file, using the obtained header:
-
-@smallexample
-@group
-$ @kbd{xsparse -v -x xhdr GNUSparseFile.6058/sparsefile}
-Reading extended header file
-Found variable GNU.sparse.size = 217481216
-Found variable GNU.sparse.numblocks = 208
-Found variable GNU.sparse.name = sparsefile
-Found variable GNU.sparse.map = 0,2048,1050624,2048,@dots{}
-Expanding file `GNUSparseFile.28124/sparsefile' to `sparsefile'
-Done
-@end group
-@end smallexample
-
-@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
-file name lengths. The binary and old @acronym{ASCII} formats have a maximum file
-length of 256, and the new @acronym{ASCII} and @acronym{CRC ASCII} formats have a max
-file length of 1024. @acronym{GNU} @command{cpio} can read and write archives
-with arbitrary file name 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 @acronym{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 @acronym{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 @acronym{BSD} source;
-@command{cpio} comes only with System III, System V, and later @acronym{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 @acronym{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 @acronym{ASCII}'' format,
-they're 18 bits---it would have to play games with the "file system @acronym{ID}"
-field of the header to make sure that the file system @acronym{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.
-
-@quotation
-What type of check sum (if any) is used, and how is this calculated.
-@end quotation
-
-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.
-
-@quotation
-If anyone knows why @command{cpio} was made when @command{tar} was present
-at the unix scene,
-@end quotation
-
-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.
-
-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.
-
-The main difference is just in the command syntax and header format.
-
-@command{tar} is a little more tape-oriented in that everything is blocked
-to start on a record boundary.
-
-@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
-
-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.
-
-@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
-
-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.
-
-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
-
-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.
-
-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.
-
-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.
-
-@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
-
-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
-@xopindex{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.
-
-@xopindex{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}.
-
-@xopindex{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.
-
-@xopindex{info-script, short description}
-@xopindex{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
-
-@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
-
-@ifclear PUBLISH
-
-@format
-errors from system:
-permission denied
-no such file or directory
-not owner
-
-errors from @command{tar}:
-directory checksum error
-header format error
-
-errors from media/system:
-i/o error
-device busy
-@end format
-
-@end ifclear
-
-@node Blocking
-@section Blocking
-@UNREVISED
-
-@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.
-
-John Gilmore, the writer of the public domain @command{tar} from which
-@GNUTAR{} was originally derived, wrote (June 1995):
-
-@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
-
-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.
-
-@menu
-* Format Variations:: Format Variations
-* Blocking Factor:: The Blocking Factor of an Archive
-@end menu
-
-@node Format Variations
-@subsection Format Variations
-@cindex Format Parameters
-@cindex Format Options
-@cindex Options, archive format specifying
-@cindex Options, format specifying
-@UNREVISED
-
-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.
-
-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 (i.e., 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
-
-@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
-(i.e., @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
-
-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
-
-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:
-
-@itemize @bullet
-
-@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
-@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
-@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
-@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
-
-@xopindex{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.
-
-@xopindex{read-full-records, short description}
-@item -B
-@itemx --read-full-records
-Reblock as we read (for reading 4.2@acronym{BSD} 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 @acronym{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.
-
-@end table
-
-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
-
-@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
-
-@noindent
-and so on for all the archives you want to put on the same tape.
-
-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:
-
-@smallexample
-$ @kbd{mt -f /dev/nrtape rewind}
-$ @kbd{mt -f /dev/nrtape fsf 16}
-$ @kbd{tar cf /dev/nrtape @var{directory-17}}
-@end smallexample
-
-In all the previous examples, we put aside blocking considerations, but
-you should do the proper things for that as well. @xref{Blocking}.
-
-@menu
-* Tape Positioning:: Tape Positions and Tape Marks
-* mt:: The @command{mt} Utility
-@end menu
-
-@node Tape Positioning
-@subsection Tape Positions and Tape Marks
-@UNREVISED
-
-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.
-
-If you think of data as a series of records "rrrr"'s, and tape marks as
-"*"'s, a tape might look like the following:
-
-@smallexample
-rrrr*rrrrrr*rrrrr*rr*rrrrr**-------------------------
-@end smallexample
-
-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}).
-
-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:
-
-@smallexample
-rrrr*rrrrrr*rrrrr*rr*rrrrr*rrr*rrrr**----------------
-@end smallexample
-
-@node mt
-@subsection The @command{mt} Utility
-@UNREVISED
-
-@FIXME{Is it true that this only works on non-block devices?
-should explain the difference, (fixed or variable).}
-@xref{Blocking Factor}.
-
-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"?}
-
-The syntax of the @command{mt} command is:
-
-@smallexample
-@kbd{mt [-f @var{tapename}] @var{operation} [@var{number}]}
-@end smallexample
-
-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:
-
-@FIXME{is there any use for record operations?}
-
-@table @option
-@item eof
-@itemx weof
-Writes @var{number} tape marks at the current position on the tape.
-
-@item fsf
-Moves tape position forward @var{number} files.
-
-@item bsf
-Moves tape position back @var{number} files.
-
-@item rewind
-Rewinds the tape. (Ignores @var{number}).
-
-@item offline
-@itemx rewoff1
-Rewinds the tape and takes the tape device off-line. (Ignores @var{number}).
-
-@item status
-Prints status information about the tape unit.
-
-@end table
-
-@FIXME{Is there a better way to frob the spacing on the list?}
-
-If you don't specify a @var{tapename}, @command{mt} uses the environment
-variable @env{TAPE}; if @env{TAPE} is not set, @command{mt} will use
-the default device specified in your @file{sys/mtio.h} file
-(@code{DEFTAPE} variable). If this is not defined, the program will
-display a descriptive error message and exit with code 1.
-
-@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.
-
-@node Using Multiple Tapes
-@section Using Multiple Tapes
-
-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} provides a special mode for creating
-multi-volume archives.
-
-@dfn{Multi-volume} archive is a single @command{tar} archive, stored
-on several media volumes of fixed size. Although in this section we will
-often call @samp{volume} a @dfn{tape}, there is absolutely no
-requirement for multi-volume archives to be stored on tapes. Instead,
-they can use whatever media type the user finds convenient, they can
-even be located on files.
-
-When creating a multi-volume archive, @GNUTAR{} continues to fill
-current volume until it runs out of space, then it switches to
-next volume (usually the operator is queried to replace the tape on
-this point), and continues working on the new volume. This operation
-continues until all requested files are dumped. If @GNUTAR{} detects
-end of media while dumping a file, such a file is archived in split
-form. Some very big files can even be split across several volumes.
-
-Each volume is itself a valid @GNUTAR{} archive, so it can be read
-without any special options. Consequently any file member residing
-entirely on one volume can be extracted or otherwise operated upon
-without needing the other volume. Sure enough, to extract a split
-member you would need all volumes its parts reside on.
-
-Multi-volume archives suffer from several limitations. In particular,
-they cannot be compressed.
-
-@GNUTAR{} is able to create multi-volume archives of two formats
-(@pxref{Formats}): @samp{GNU} and @samp{POSIX}.
-
-@menu
-* Multi-Volume Archives:: Archives Longer than One Tape or Disk
-* Tape Files:: Tape Files
-* Tarcat:: Concatenate Volumes into a Single Archive
-
-@end menu
-
-@node Multi-Volume Archives
-@subsection Archives Longer than One Tape or Disk
-@cindex Multi-volume archives
-
-@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.
-
-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.
-
-@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.
-For example:
-
-@smallexample
-$ @kbd{tar --create --multi-volume --file=/dev/tape @var{files}}
-@end smallexample
-@end table
-
-The method @command{tar} uses to detect end of tape is not perfect, and
-fails on some operating systems or on some devices. If @command{tar}
-cannot detect the end of the tape itself, you can use
-@option{--tape-length} option to inform it about the capacity of the
-tape:
-
-@anchor{tape-length}
-@table @option
-@opindex tape-length
-@item --tape-length=@var{size}
-@itemx -L @var{size}
-Set maximum length of a volume. The @var{size} argument should then
-be the usable size of the tape in units of 1024 bytes. This option
-selects @option{--multi-volume} automatically. For example:
-
-@smallexample
-$ @kbd{tar --create --tape-length=41943040 --file=/dev/tape @var{files}}
-@end smallexample
-@end table
-
-@anchor{change volume prompt}
-When @GNUTAR{} comes to the end of a storage media, it asks you to
-change the volume. The built-in prompt for POSIX locale
-is@footnote{If you run @GNUTAR{} under a different locale, the
-translation to the locale's language will be used.}:
-
-@smallexample
-Prepare volume #@var{n} for `@var{archive}' and hit return:
-@end smallexample
-
-@noindent
-where @var{n} is the ordinal number of the volume to be created and
-@var{archive} is archive file or device name.
-
-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}@footnote{@xref{--restrict}, for more information about
-this option}.
-@item y
-Request @command{tar} to begin writing the next volume.
-@end table
-
-(You should only type @samp{y} after you have changed the tape;
-otherwise @command{tar} will write over the volume it just finished.)
-
-@cindex Volume number file
-@cindex volno file
-@anchor{volno-file}
-@opindex volno-file
-The volume number used by @command{tar} in its tape-changing prompt
-can be changed; if you give the
-@option{--volno-file=@var{file-of-number}} option, then
-@var{file-of-number} should be an non-existing 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.)
-
-@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, you can write a special
-@dfn{new volume script}, that will be responsible for changing the
-volume, and instruct @command{tar} to use it instead of its normal
-prompting procedure:
-
-@table @option
-@item --info-script=@var{script-name}
-@itemx --new-volume-script=@var{script-name}
-@itemx -F @var{script-name}
-Specify the full name of the volume script to use. The script can be
-used to eject cassettes, or to broadcast messages such as
-@samp{Someone please come change my tape} when performing unattended
-backups.
-@end table
-
-The @var{script-name} is executed without any command line
-arguments. It inherits @command{tar}'s shell environment.
-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_BLOCKING_FACTOR, info script environment variable
-@item TAR_BLOCKING_FACTOR
-Current blocking factor (@pxref{Blocking}.
-
-@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
-A short option describing the operation @command{tar} is executing
-@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.
-
-@vrindex TAR_FD, info script environment variable
-@item TAR_FD
-File descriptor which can be used to communicate the new volume
-name to @command{tar}.
-@end table
-
-The volume script can instruct @command{tar} to use new archive name,
-by writing in to file descriptor @env{$TAR_FD} (see below for an example).
-
-If the info script fails, @command{tar} exits; otherwise, it begins
-writing the next volume.
-
-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). For example, suppose 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
-
-The second method is to use the @samp{n} response to the tape-change
-prompt.
-
-Finally, the most flexible approach is to use a volume script, that
-writes new archive name to the file descriptor @env{$TAR_FD}. For example, the
-following volume script will create a series of archive files, named
-@file{@var{archive}-@var{vol}}, where @var{archive} is the name of the
-archive being created (as given by @option{--file} option) and
-@var{vol} is the ordinal number of the archive being created:
-
-@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 >&$TAR_FD
-@end group
-@end smallexample
-
-The same script can be used while listing, comparing or extracting
-from the created archive. For example:
-
-@smallexample
-@group
-# @r{Create a multi-volume archive:}
-$ @kbd{tar -c -L1024 -f archive.tar -F new-volume .}
-# @r{Extract from the created archive:}
-$ @kbd{tar -x -f archive.tar -F new-volume .}
-@end group
-@end smallexample
-
-@noindent
-Notice, that the first command had to use @option{-L} option, since
-otherwise @GNUTAR{} will end up writing everything to file
-@file{archive.tar}.
-
-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}.
-
-If an archive member is split across volumes (i.e., 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.
-
-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.
-
-If a multi-volume archive was labeled using
-@option{--label=@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.
-
-Notice that multi-volume support is a GNU extension and the archives
-created in this mode should be read only using @GNUTAR{}. If you
-absolutely have to process such archives using a third-party @command{tar}
-implementation, read @ref{Split Recovery}.
-
-@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
-@cindex Labeling multi-volume archives
-@UNREVISED
-
-@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.
-
-@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
-
- 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
-explicitly 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 labeled 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
-
-@noindent
-in case its label does not match. This will work even if
-@file{archive} is not labeled 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
-
-@table @option
-@item -W
-@itemx --verify
-@opindex verify, short description
-Attempt to verify the archive after writing.
-@end table
-
-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.
-
-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.
-
-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.
-
-@xopindex{verify, using with @option{--create}}
-@xopindex{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.
-
-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.
-
-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
-
-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).
-
-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.
-
-@node Changes
-@appendix Changes
-
-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}.
-
-@table @asis
-@item Use of globbing patterns when listing and extracting.
-
-Previous versions of GNU tar assumed shell-style globbing when
-extracting from or listing an archive. For example:
-
-@smallexample
-$ @kbd{tar xf foo.tar '*.c'}
-@end smallexample
-
-would extract all files whose names end in @samp{.c}. This behavior
-was not documented and was incompatible with traditional tar
-implementations. Therefore, starting from version 1.15.91, GNU tar
-no longer uses globbing by default. For example, the above invocation
-is now interpreted as a request to extract from the archive the file
-named @file{*.c}.
-
-To facilitate transition to the new behavior for those users who got
-used to the previous incorrect one, @command{tar} will print a warning
-if it finds out that a requested member was not found in the archive
-and its name looks like a globbing pattern. For example:
-
-@smallexample
-$ @kbd{tar xf foo.tar '*.c'}
-tar: Pattern matching characters used in file names. Please,
-tar: use --wildcards to enable pattern matching, or --no-wildcards to
-tar: suppress this warning.
-tar: *.c: Not found in archive
-tar: Error exit delayed from previous errors
-@end smallexample
-
-To treat member names as globbing patterns, use --wildcards option.
-If you want to tar to mimic the behavior of versions prior to 1.15.91,
-add this option to your @env{TAR_OPTIONS} variable.
-
-@xref{wildcards}, for the detailed discussion of the use of globbing
-patterns by @GNUTAR{}.
-
-@item Use of short option @option{-o}.
-
-Earlier versions of @GNUTAR{} understood @option{-o} command line
-option as a synonym for @option{--old-archive}.
-
-@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.
-
-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.
-
-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.
-
-@FIXME{Change the first argument to tar-formats when the new Automake is
-out. The proposition to add @anchor{} to the appropriate place of its
-docs was accepted by Automake people --Sergey 2006-05-25}.
-@xref{Options, tar-v7, Changing Automake's Behavior,
-automake, GNU Automake}, for a description on how to use various
-archive formats with @command{automake}.
-
-Future versions of @GNUTAR{} will understand @option{-o} only as a
-synonym for @option{--no-same-owner}.
-
-@item Use of short option @option{-l}
-
-Earlier versions of @GNUTAR{} understood @option{-l} option as a
-synonym for @option{--one-file-system}. Since such usage contradicted
-to UNIX98 specification and harmed compatibility with other
-implementation, it was declared deprecated in version 1.14. However,
-to facilitate transition to its new semantics, it was supported by
-versions 1.15 and 1.15.90. The present use of @option{-l} as a short
-variant of @option{--check-links} was introduced in version 1.15.91.
-
-@item Use of options @option{--portability} and @option{--old-archive}
-
-These options are deprecated. Please use @option{--format=v7} instead.
-
-@item Use of option @option{--posix}
-
-This option is deprecated. Please use @option{--format=posix} instead.
-@end table
-
-@node Configuring Help Summary
-@appendix Configuring Help Summary
-
-Running @kbd{tar --help} displays the short @command{tar} option
-summary (@pxref{help}). This summary is organized 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
-
-@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
-
-Following variables are declared:
-
-@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:
-
-@smallexample
- -f ARCHIVE, --file=ARCHIVE use archive file or device ARCHIVE
-@end smallexample
-
-If false, then if an option has both short and long forms, the
-argument is only shown with the long one, for example:
-
-@smallexample
- -f, --file=ARCHIVE use archive file or device ARCHIVE
-@end smallexample
-
-@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 default is false.
-@end deftypevr
-
-@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:
-
-@quotation
-Mandatory or optional arguments to long options are also mandatory or
-optional for any corresponding short options.
-@end quotation
-
-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
-
-@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
-
-@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.
-
-The default value is 1.
-@end deftypevr
-
-@deftypevr {Help Output} offset usage-indent
-Indentation of wrapped usage lines. Affects @option{--usage}
-output. Default is 12.
-@end deftypevr
-
-@deftypevr {Help Output} offset rmargin
-Right margin of the text output. Used for wrapping.
-@end deftypevr
-
-@node Fixing Snapshot Files
-@appendix Fixing Snapshot Files
-@include tar-snapshot-edit.texi
-
-@node Tar Internals
-@appendix Tar Internals
-@include intern.texi
-
-@node Genfile
-@appendix Genfile
-@include genfile.texi
-
-@node Free Software Needs Free Documentation
-@appendix Free Software Needs Free Documentation
-@include freemanuals.texi
-
-@node Copying This Manual
-@appendix Copying This Manual
-
-@menu
-* GNU Free Documentation License:: License for copying this manual
-@end menu
-
-@include fdl.texi
-
-@node Index of Command Line Options
-@appendix Index of Command Line Options
-
-This appendix contains an index of all @GNUTAR{} long command line
-options. The options are listed without the preceding double-dash.
-For a cross-reference of short command line options, @ref{Short Option Summary}.
-
-@printindex op
-
-@node Index
-@appendix Index
-
-@printindex cp
-
-@summarycontents
-@contents
-@bye
-
-@c Local variables:
-@c texinfo-column-for-description: 32
-@c End:
projects / tar / blobdiff