Upload Tizen:Base source

1 files changed, 7594 insertions, 0 deletions

diff --git a/doc/tar.info-1 b/doc/tar.info-1
new file mode 100644
index 0000000..362a137
--- /dev/null
+++ b/doc/tar.info-1
@@ -0,0 +1,7594 @@
+This is tar.info, produced by makeinfo version 4.8 from tar.texi.
+
+   This manual is for GNU `tar' (version 1.17, 8 June 2007), which
+creates and extracts files from archives.
+
+   Copyright (C) 1992, 1994, 1995, 1996, 1997, 1999, 2000, 2001, 2003,
+2004, 2005, 2006, 2007 Free Software Foundation, Inc.
+
+     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 are free to copy and modify
+     this GNU Manual.  Buying copies from GNU Press supports the FSF in
+     developing GNU and promoting software freedom."
+
+INFO-DIR-SECTION Archiving
+START-INFO-DIR-ENTRY
+* Tar: (tar).                   Making tape (or disk) archives.
+END-INFO-DIR-ENTRY
+
+INFO-DIR-SECTION Individual utilities
+START-INFO-DIR-ENTRY
+* tar: (tar)tar invocation.                     Invoking GNU `tar'.
+END-INFO-DIR-ENTRY
+
+
+File: tar.info,  Node: Top,  Next: Introduction,  Up: (dir)
+
+GNU tar: an archiver tool
+*************************
+
+This manual is for GNU `tar' (version 1.17, 8 June 2007), which creates
+and extracts files from archives.
+
+   Copyright (C) 1992, 1994, 1995, 1996, 1997, 1999, 2000, 2001, 2003,
+2004, 2005, 2006, 2007 Free Software Foundation, Inc.
+
+     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 are free to copy and modify
+     this GNU Manual.  Buying copies from GNU Press supports the FSF in
+     developing GNU and promoting software freedom."
+
+   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.
+
+* Menu:
+
+* Introduction::
+* Tutorial::
+* tar invocation::
+* operations::
+* Backups::
+* Choosing::
+* Date input formats::
+* Formats::
+* Media::
+
+Appendices
+
+* Changes::
+* Configuring Help Summary::
+* Tar Internals::
+* Genfile::
+* Free Software Needs Free Documentation::
+* Copying This Manual::
+* Index of Command Line Options::
+* Index::
+
+ --- The Detailed Node Listing ---
+
+Introduction
+
+* Book Contents::               What this Book Contains
+* Definitions::                 Some Definitions
+* What tar Does::               What `tar' Does
+* Naming tar Archives::         How `tar' Archives are Named
+* Authors::                     GNU `tar' Authors
+* Reports::                     Reporting bugs or suggestions
+
+Tutorial Introduction to `tar'
+
+* assumptions::
+* stylistic conventions::
+* basic tar options::           Basic `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 GNU `tar'
+
+* Synopsis::
+* using tar options::
+* Styles::
+* All Options::
+* help::
+* defaults::
+* verbose::
+* 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 `tar' Options
+
+* Operation Summary::
+* Option Summary::
+* Short Option Summary::
+
+GNU `tar' Operations
+
+* Basic tar::
+* Advanced tar::
+* create options::
+* extract options::
+* backup::
+* Applications::
+* looking ahead::
+
+Advanced GNU `tar' Operations
+
+* Operations::
+* append::
+* update::
+* concatenate::
+* delete::
+* compare::
+
+How to Add Files to Existing Archives: `--append'
+
+* appending files::             Appending Files to an Archive
+* multiple::
+
+Updating an Archive
+
+* how to update::
+
+Options Used by `--create'
+
+* override::                  Overriding File Metadata.
+* Ignore Failed Read::
+
+Options Used by `--extract'
+
+* Reading::                     Options to Help Read Archives
+* Writing::                     Changing How `tar' Writes Files
+* Scarce::                      Coping with Scarce Resources
+
+Options to Help Read Archives
+
+* read full records::
+* Ignore Zeros::
+
+Changing How `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 `tar' to Perform Full Dumps
+* Incremental Dumps::           Using `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 `Backup-specs'
+
+Choosing Files and Names for `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::                EST, PDT, 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
+
+* Portability::                 Making `tar' Archives More Portable
+* Compression::                 Using Less Space through Compression
+* Attributes::                  Handling File Attributes
+* cpio::                        Comparison of `tar' and `cpio'
+
+Making `tar' Archives More Portable
+
+* Portable Names::              Portable Names
+* dereference::                 Symbolic Links
+* old::                         Old V7 Archives
+* ustar::                       Ustar Archives
+* gnu::                         GNU and old GNU format archives.
+* posix::                       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 `tar' Implementations
+
+GNU `tar' and POSIX `tar'
+
+* PAX keywords:: Controlling Extended Header Keywords.
+
+How to Extract GNU-Specific Data Using Other `tar' Implementations
+
+* Split Recovery::       Members Split Between Volumes
+* Sparse Recovery::      Sparse Members
+
+Using Less Space through Compression
+
+* gzip::                        Creating and Reading Compressed Archives
+* sparse::                      Archiving Sparse Files
+
+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 `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::         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
+
+
+File: tar.info,  Node: Introduction,  Next: Tutorial,  Prev: Top,  Up: Top
+
+1 Introduction
+**************
+
+GNU `tar' creates and manipulates "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 `tar' Does
+* Naming tar Archives::         How `tar' Archives are Named
+* Authors::                     GNU `tar' Authors
+* Reports::                     Reporting bugs or suggestions
+
+
+File: tar.info,  Node: Book Contents,  Next: Definitions,  Up: Introduction
+
+1.1 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 GNU
+`tar' and its documentation, and where you should send bug reports or
+comments.
+
+   The second chapter is a tutorial (*note Tutorial::) which provides a
+gentle introduction for people who are new to using `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 `tar', it is not intended solely for beginners.  The
+tutorial explains how to use the three most frequently used operations
+(`create', `list', and `extract') as well as two frequently used
+options (`file' and `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; *note Tutorial::.)
+
+   The third chapter presents the remaining five operations, and
+information about using `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 (*note Date input formats::) exists in its
+entirety in other GNU manuals, and is mostly self-contained.  In
+addition, one section of this manual (*note Standard::) contains a big
+quote which is taken directly from `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.)
+
+
+File: tar.info,  Node: Definitions,  Next: What tar Does,  Prev: Book Contents,  Up: Introduction
+
+1.2 Some Definitions
+====================
+
+The `tar' program is used to create and manipulate `tar' archives.  An
+"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 `tar' to "create" a new
+archive in a specified directory.
+
+   The files inside an archive are called "members".  Within this
+manual, we use the term "file" to refer only to files accessible in the
+normal ways (by `ls', `cat', and so forth), and the term "member" to
+refer only to the members of an archive.  Similarly, a "file name" is
+the name of a file, as it resides in the file system, and a "member
+name" is the name of an archive member within the archive.
+
+   The term "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 "extracting the archive".
+The term "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 "list" the members in a given archive (this is often thought
+of as "printing" them to the standard output, or the command line), or
+"append" members to a pre-existing archive.  All of these operations
+can be performed using `tar'.
+
+
+File: tar.info,  Node: What tar Does,  Next: Naming tar Archives,  Prev: Definitions,  Up: Introduction
+
+1.3 What `tar' Does
+===================
+
+The `tar' program provides the ability to create `tar' archives, as
+well as various other kinds of manipulation.  For example, you can use
+`tar' on previously created archives to extract files, to store
+additional files, or to update or list files which were already stored.
+
+   Initially, `tar' archives were used to store files conveniently on
+magnetic tape.  The name `tar' comes from this use; it stands for
+`t'ape `ar'chiver.  Despite the utility's name, `tar' can direct its
+output to available devices, files, or other programs (using pipes).
+`tar' may even access remote devices or files (as archives).
+
+   You can use `tar' archives in many ways.  We want to stress a few of
+them: storage, backup, and transportation.
+
+Storage
+     Often, `tar' archives are used to store related files for
+     convenient file transfer over a network.  For example, the GNU
+     Project distributes its software bundled into `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 `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 `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 `tar' can be used to move
+     archives in all dimensions, even time!)
+
+Backup
+     Because the archive created by `tar' is capable of preserving file
+     information and directory structure, `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.  GNU
+     `tar' has special features that allow it to be used to make
+     incremental and full dumps of all the files in a file system.
+
+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.
+
+
+File: tar.info,  Node: Naming tar Archives,  Next: Authors,  Prev: What tar Does,  Up: Introduction
+
+1.4 How `tar' Archives are Named
+================================
+
+Conventionally, `tar' archives are given names ending with `.tar'.
+This is not necessary for `tar' to operate properly, but this manual
+follows that convention in order to accustom readers to it and to make
+examples more clear.
+
+   Often, people refer to `tar' archives as "`tar' files," and archive
+members as "files" or "entries".  For people familiar with the
+operation of `tar', this causes no difficulty.  However, in this
+manual, we consistently refer to "archives" and "archive members" to
+make learning to use `tar' easier for novice users.
+
+
+File: tar.info,  Node: Authors,  Next: Reports,  Prev: Naming tar Archives,  Up: Introduction
+
+1.5 GNU `tar' Authors
+=====================
+
+GNU `tar' was originally written by John Gilmore, and modified by many
+people.  The GNU enhancements were written by Jay Fenlason, then Joy
+Kendall, and the whole package has been further maintained by Thomas
+Bushnell, n/BSG, Franc,ois Pinard, Paul Eggert, and finally Sergey
+Poznyakoff with the help of numerous and kind users.
+
+   We wish to stress that `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 `THANKS' file
+from the GNU `tar' distribution.
+
+   Jay Fenlason put together a draft of a GNU `tar' 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 GNU `tar'.  Franc,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 1.17
+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 *note
+Backups::.
+
+   In July, 2003 GNU `tar' was put on CVS at savannah.gnu.org (see
+`http://savannah.gnu.org/projects/tar'), and active development and
+maintenance work has started again.  Currently GNU `tar' is being
+maintained by Paul Eggert, Sergey Poznyakoff and Jeff Bailey.
+
+   Support for POSIX archives was added by Sergey Poznyakoff.
+
+
+File: tar.info,  Node: Reports,  Prev: Authors,  Up: Introduction
+
+1.6 Reporting bugs or suggestions
+=================================
+
+If you find problems or have suggestions about this program or manual,
+please report them to `bug-tar@gnu.org'.
+
+   When reporting a bug, please be sure to include as much detail as
+possible, in order to reproduce it.  .
+
+
+File: tar.info,  Node: Tutorial,  Next: tar invocation,  Prev: Introduction,  Up: Top
+
+2 Tutorial Introduction to `tar'
+********************************
+
+This chapter guides you through some basic examples of three `tar'
+operations: `--create', `--list', and `--extract'.  If you already know
+how to use some other version of `tar', then you may not need to read
+this chapter.  This chapter omits most complicated details about how
+`tar' works.
+
+* Menu:
+
+* assumptions::
+* stylistic conventions::
+* basic tar options::           Basic `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::
+
+
+File: tar.info,  Node: assumptions,  Next: stylistic conventions,  Up: Tutorial
+
+2.1 Assumptions this Tutorial Makes
+===================================
+
+This chapter is paced to allow beginners to learn about `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:
+
+   * Before you start to work through this tutorial, you should
+     understand what the terms "archive" and "archive member" mean
+     (*note Definitions::).  In addition, you should understand
+     something about how Unix-type operating systems work, and you
+     should know how to use some basic utilities.  For example, you
+     should know how to create, list, copy, rename, edit, and delete
+     files and directories; how to change between directories; and how
+     to figure out where you are in the file system.  You should have
+     some basic understanding of directory structure and how files are
+     named according to which directory they are in.  You should
+     understand concepts such as standard output and standard input,
+     what various definitions of the term "argument" mean, and the
+     differences between relative and absolute file names.
+
+   * 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 `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
+     `/home/fsf/melissa'.  All of my examples are in a subdirectory of
+     the directory named by that file name; the subdirectory is called
+     `practice'.
+
+   * 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.  *Note Media::,
+     for complete information on using `tar' archives with tape drives.
+
+
+
+File: tar.info,  Node: stylistic conventions,  Next: basic tar options,  Prev: assumptions,  Up: Tutorial
+
+2.2 Stylistic Conventions
+=========================
+
+In the examples, `$' represents a typical shell prompt.  It precedes
+lines you should type; to make this more clear, those lines are shown
+in `this font', as opposed to lines which represent the computer's
+response; those lines are shown in `this font', or sometimes `like
+this'.
+
+
+File: tar.info,  Node: basic tar options,  Next: frequent operations,  Prev: stylistic conventions,  Up: Tutorial
+
+2.3 Basic `tar' Operations and Options
+======================================
+
+`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 `tar' fall into one of two classes:
+operations, and options.
+
+   Some arguments fall into a class called "operations"; exactly one of
+these is both allowed and required for any instance of using `tar'; you
+may _not_ specify more than one.  People sometimes speak of "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 "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 `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 `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 GNU `tar' for compatibility with Unix
+`tar'.  In this book we present a full discussion of this way of
+writing options and operations (*note Old Options::), and we discuss
+the other two styles of writing options (*Note Long Options::, and
+*note 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 `tar' commands easier.  For
+example, instead of typing
+
+     tar --create --verbose --file=afiles.tar apple angst aspic
+
+you can type
+     tar -c -v -f afiles.tar apple angst aspic
+
+or even
+     tar -cvf afiles.tar apple angst aspic
+
+For more information on option syntax, see *note 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, _optional_ "options" in certain
+general class statements.  For example, we just talked about "short and
+long forms of options and operations".  However, experienced `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 `tar' "commands".  A
+`tar' "command" is the entire command line of user input which tells
+`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 `tar' command".  When the word "command"
+is used specifically like this, a person is usually referring to the
+`tar' _operation_, not the whole line.  Again, use context to figure
+out which of the meanings the speaker intends.
+
+
+File: tar.info,  Node: frequent operations,  Next: Two Frequent Options,  Prev: basic tar options,  Up: Tutorial
+
+2.4 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.
+
+`--create'
+`-c'
+     Create a new `tar' archive.
+
+`--list'
+`-t'
+     List the contents of an archive.
+
+`--extract'
+`-x'
+     Extract one or more members from an archive.
+
+
+File: tar.info,  Node: Two Frequent Options,  Next: create,  Prev: frequent operations,  Up: Tutorial
+
+2.5 Two Frequently Used Options
+===============================
+
+To understand how to run `tar' in the three operating modes listed
+previously, you also need to understand how to use two of the options to
+`tar': `--file' (which takes an archive file as an argument) and
+`--verbose'.  (You are usually not _required_ to specify either of
+these options when you run `tar', but they can be very useful in making
+things more clear and helping you avoid errors.)
+
+* Menu:
+
+* file tutorial::
+* verbose tutorial::
+* help tutorial::
+
+
+File: tar.info,  Node: file tutorial,  Next: verbose tutorial,  Up: Two Frequent Options
+
+The `--file' Option
+-------------------
+
+`--file=ARCHIVE-NAME'
+`-f ARCHIVE-NAME'
+     Specify the name of an archive file.
+
+   You can specify an argument for the `--file=ARCHIVE-NAME' (`-f
+ARCHIVE-NAME') option whenever you use `tar'; this option determines
+the name of the archive file that `tar' will work on.
+
+   If you don't specify this argument, then `tar' will examine the
+environment variable `TAPE'.  If it is set, its value will be used as
+the archive name.  Otherwise, `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 `tar --show-defaults', *note defaults::).  If
+there is no tape drive attached, or the default is not meaningful, then
+`tar' will print an error message.  The error message might look
+roughly like one of the following:
+
+     tar: can't open /dev/rmt8 : No such device or address
+     tar: can't open /dev/rsmt0 : I/O error
+
+To avoid confusion, we recommend that you always specify an archive file
+name by using `--file=ARCHIVE-NAME' (`-f ARCHIVE-NAME') when writing
+your `tar' commands.  For more information on using the
+`--file=ARCHIVE-NAME' (`-f ARCHIVE-NAME') option, see *note file::.
+
+
+File: tar.info,  Node: verbose tutorial,  Next: help tutorial,  Prev: file tutorial,  Up: Two Frequent Options
+
+The `--verbose' Option
+----------------------
+
+`--verbose'
+`-v'
+     Show the files being worked on as `tar' is running.
+
+   `--verbose' (`-v') shows details about the results of running `tar'.
+This can be especially useful when the results might not be obvious.
+For example, if you want to see the progress of `tar' as it writes
+files into the archive, you can use the `--verbose' option.  In the
+beginning, you may find it useful to use `--verbose' at all times; when
+you are more accustomed to `tar', you will likely want to use it at
+certain times but not at others.  We will use `--verbose' at times to
+help make something clear, and we will give many examples both using
+and not using `--verbose' to show the differences.
+
+   Each instance of `--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 (`--list', `--extract', `--diff'), `tar' by
+default prints only the names of the members being extracted.  Using
+`--verbose' will show a full, `ls' style member listing.
+
+   In contrast, when writing archives (`--create', `--append',
+`--update'), `tar' does not print file names by default.  So, a single
+`--verbose' option shows the file names being added to the archive,
+while two `--verbose' options enable the full listing.
+
+   For example, to create an archive in verbose mode:
+
+     $ tar -cvf afiles.tar apple angst aspic
+     apple
+     angst
+     aspic
+
+Creating the same archive with the verbosity level 2 could give:
+
+     $ 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
+
+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:
+
+     $ tar --create --verbose --verbose ...
+
+Note that you must double the hyphens properly each time.
+
+   Later in the tutorial, we will give examples using
+`--verbose --verbose'.
+
+   The full output consists of six fields:
+
+   * File type and permissions in symbolic form.  These are displayed
+     in the same format as the first column of `ls -l' output (*note
+     format=verbose: (fileutils)What information is listed.).
+
+   * Owner name and group separated by a slash character.  If these
+     data are not available (for example, when listing a `v7' format
+     archive), numeric ID values are printed instead.
+
+   * Size of the file, in bytes.
+
+   * File modification date in ISO 8601 format.
+
+   * File modification time.
+
+   * File name.  If the name contains any special characters (white
+     space, newlines, etc.) these are displayed in an unambiguous form
+     using so called "quoting style".  For the detailed discussion of
+     available styles and on how to use them, see *note quoting
+     styles::.
+
+     Depending on the file type, the name can be followed by some
+     additional information, described in the following table:
+
+    `-> LINK-NAME'
+          The file or archive member is a "symbolic link" and LINK-NAME
+          is the name of file it links to.
+
+    `link to LINK-NAME'
+          The file or archive member is a "hard link" and LINK-NAME is
+          the name of file it links to.
+
+    `--Long Link--'
+          The archive member is an old GNU format long link.  You will
+          normally not encounter this.
+
+    `--Long Name--'
+          The archive member is an old GNU format long name.  You will
+          normally not encounter this.
+
+    `--Volume Header--'
+          The archive member is a GNU "volume header" (*note Tape
+          Files::).
+
+    `--Continued at byte N--'
+          Encountered only at the beginning of a multi-volume archive
+          (*note Using Multiple Tapes::).  This archive member is a
+          continuation from the previous volume. The number N gives the
+          offset where the original file was split.
+
+    `unknown file type C'
+          An archive member of unknown type. 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 GNU `tar' is not able to handle, or the archive is
+          corrupted.
+
+
+   For example, here is an archive listing containing most of the
+special suffixes explained above:
+
+     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
+
+
+
+File: tar.info,  Node: help tutorial,  Prev: verbose tutorial,  Up: Two Frequent Options
+
+Getting Help: Using the `--help' Option
+---------------------------------------
+
+`--help'
+     The `--help' option to `tar' prints out a very brief list of all
+     operations and option available for the current version of `tar'
+     available on your system.
+
+
+File: tar.info,  Node: create,  Next: list,  Prev: Two Frequent Options,  Up: Tutorial
+
+2.6 How to Create Archives
+==========================
+
+     _(This message will disappear, once this node revised.)_
+
+One of the basic operations of `tar' is `--create' (`-c'), which you
+use to create a `tar' archive.  We will explain `--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 _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 `blues',
+`folk', and `jazz'.  The archive is called `collection.tar'.
+
+   This section will proceed slowly, detailing how to use `--create' in
+`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 `tar' works.
+
+* Menu:
+
+* prepare for examples::
+* Creating the archive::
+* create verbose::
+* short create::
+* create dir::
+
+
+File: tar.info,  Node: prepare for examples,  Next: Creating the archive,  Up: create
+
+2.6.1 Preparing a Practice Directory for Examples
+-------------------------------------------------
+
+To follow along with this and future examples, create a new directory
+called `practice' containing files called `blues', `folk' and `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 `practice' is a subdirectory of your
+home directory.
+
+   Now `cd' to the directory named `practice'; `practice' is now your
+"working directory".  (_Please note_: Although the full file name of
+this directory is `/HOMEDIR/practice', in our examples we will refer to
+this directory as `practice'; the 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 `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,
+`collection.tar'), or that you don't care about its contents.  Whenever
+you use `create', `tar' will erase the current contents of the file
+named by `--file=ARCHIVE-NAME' (`-f ARCHIVE-NAME') if it exists.  `tar'
+will not tell you if you are about to overwrite an archive unless you
+specify an option which does this (*note 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 `--append' (`-r'); see *note append:: for
+information on how to do this.
+
+
+File: tar.info,  Node: Creating the archive,  Next: create verbose,  Prev: prepare for examples,  Up: create
+
+2.6.2 Creating the Archive
+--------------------------
+
+To place the files `blues', `folk', and `jazz' into an archive named
+`collection.tar', use the following command:
+
+     $ tar --create --file=collection.tar blues folk jazz
+
+   The order of the arguments is not very important, _when using long
+option forms_.  You could also say:
+
+     $ tar blues --create folk --file=collection.tar jazz
+
+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
+`tar', to avoid errors).
+
+   Note that the sequence `--file=collection.tar' is considered to be
+_one_ argument.  If you substituted any other string of characters for
+`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.
+*Note short create::, for more information on this.
+
+   In this example, you type the command as shown above: `--create' is
+the operation which creates the new archive (`collection.tar'), and
+`--file' is the option which lets you give it the name you chose.  The
+files, `blues', `folk', and `jazz', are now members of the archive,
+`collection.tar' (they are "file name arguments" to the `--create'
+operation.  *Note Choosing::, for the detailed discussion on these.)
+Now that they are in the archive, they are called _archive members_,
+not files.  (*note members: Definitions.).
+
+   When you create an archive, you _must_ specify which files you want
+placed in the archive.  If you do not specify any archive members, GNU
+`tar' will complain.
+
+   If you now list the contents of the working directory (`ls'), you
+will find the archive file listed as well as the files you saw
+previously:
+
+     blues   folk   jazz   collection.tar
+
+Creating the archive `collection.tar' did not destroy the copies of the
+files in the directory.
+
+   Keep in mind that if you don't indicate an operation, `tar' will not
+run and will prompt you for one.  If you don't name any files, `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.
+
+   _Caution_: Do not attempt to use `--create' (`-c') to add files to
+an existing archive; it will delete the archive and write a new one.
+Use `--append' (`-r') instead.  *Note append::.
+
+
+File: tar.info,  Node: create verbose,  Next: short create,  Prev: Creating the archive,  Up: create
+
+2.6.3 Running `--create' with `--verbose'
+-----------------------------------------
+
+If you include the `--verbose' (`-v') option on the command line, `tar'
+will list the files it is acting on as it is working.  In verbose mode,
+the `create' example above would appear as:
+
+     $ tar --create --verbose --file=collection.tar blues folk jazz
+     blues
+     folk
+     jazz
+
+   This example is just like the example we showed which did not use
+`--verbose', except that `tar' generated the remaining lines .
+
+   In the rest of the examples in this chapter, we will frequently use
+`verbose' mode so we can show actions or `tar' responses that you would
+otherwise not see, and which are important for you to understand.
+
+
+File: tar.info,  Node: short create,  Next: create dir,  Prev: create verbose,  Up: create
+
+2.6.4 Short Forms with `create'
+-------------------------------
+
+As we said before, the `--create' (`-c') operation is one of the most
+basic uses of `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 *note Styles::; for now, here is what the previous
+example (including the `--verbose' (`-v') option) looks like using
+short option forms:
+
+     $ tar -cvf collection.tar blues folk jazz
+     blues
+     folk
+     jazz
+
+As you can see, the system responds the same no matter whether you use
+long or short option forms.
+
+   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:
+
+     $ tar -cfv collection.tar blues folk jazz
+
+In this case, `tar' will make an archive file called `v', containing
+the files `blues', `folk', and `jazz', because the `v' is the closest
+"file name" to the `-f' option, and is thus taken to be the chosen
+archive file name.  `tar' will try to add a file called
+`collection.tar' to the `v' archive file; if the file `collection.tar'
+did not already exist, `tar' will report an error indicating that this
+file does not exist.  If the file `collection.tar' does already exist
+(e.g., from a previous command you may have run), then `tar' will add
+this file to the archive.  Because the `-v' option did not get
+registered, `tar' will not run under `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,
+
+     $ tar blues --create folk --file=collection.tar jazz
+
+is confusing as it is.  When shown using short forms, however, it
+becomes much more so:
+
+     $ tar blues -c folk -f collection.tar jazz
+
+It would be very easy to put the wrong string of characters immediately
+following the `-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.
+
+
+File: tar.info,  Node: create dir,  Prev: short create,  Up: create
+
+2.6.5 Archiving Directories
+---------------------------
+
+You can archive a directory by specifying its directory name as a file
+name argument to `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:
+
+     $ cd ..
+     $
+
+This will put you into the directory which contains `practice', i.e.,
+your home directory.  Once in the superior directory, you can specify
+the subdirectory, `practice', as a file name argument.  To store
+`practice' in the new archive file `music.tar', type:
+
+     $ tar --create --verbose --file=music.tar practice
+
+`tar' should output:
+
+     practice/
+     practice/blues
+     practice/folk
+     practice/jazz
+     practice/collection.tar
+
+   Note that the archive thus created is not in the subdirectory
+`practice', but rather in the current working directory--the directory
+from which `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 `tar'.  For example, you will probably not be able to
+store your home directory in an archive by invoking `tar' from the root
+directory; *Note absolute::.  (Note also that `collection.tar', the
+original archive file, has itself been archived.  `tar' will accept any
+file as a file to be archived, regardless of its content.  When
+`music.tar' is extracted, the archive file `collection.tar' will be
+re-written into the file system).
+
+   If you give `tar' a command such as
+
+     $ tar --create --file=foo.tar .
+
+`tar' will report `tar: ./foo.tar is the archive; not dumped'.  This
+happens because `tar' creates the archive `foo.tar' in the current
+directory before putting any files into it.  Then, when `tar' attempts
+to add all the files in the directory `.' to the archive, it notices
+that the file `./foo.tar' is the same as the archive `foo.tar', and
+skips it.  (It makes no sense to put an archive into itself.)  GNU `tar'
+will continue in this case, and create the archive normally, except for
+the exclusion of that one file.  (_Please note:_ Other implementations
+of `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 GNU `tar'.  In general, it is wise to always
+place the archive outside of the directory being dumped.
+
+
+File: tar.info,  Node: list,  Next: extract,  Prev: create,  Up: Tutorial
+
+2.7 How to List Archives
+========================
+
+Frequently, you will find yourself wanting to determine exactly what a
+particular archive contains.  You can use the `--list' (`-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 `collection.tar' that you
+created in the last section with the command,
+
+     $ tar --list --file=collection.tar
+
+The output of `tar' would then be:
+
+     blues
+     folk
+     jazz
+
+The archive `bfiles.tar' would list as follows:
+
+     ./birds
+     baboon
+     ./box
+
+Be sure to use a `--file=ARCHIVE-NAME' (`-f ARCHIVE-NAME') option just
+as with `--create' (`-c') to specify the name of the archive.
+
+   If you use the `--verbose' (`-v') option with `--list', then `tar'
+will print out a listing reminiscent of `ls -l', showing owner, file
+size, and so forth.  This output is described in detail in *note
+verbose member listing::.
+
+   If you had used `--verbose' (`-v') mode, the example above would
+look like:
+
+     $ tar --list --verbose --file=collection.tar folk
+     -rw-r--r-- myself user 62 1990-05-23 10:55 folk
+
+   It is important to notice that the output of `tar --list --verbose'
+does not necessarily match that produced by `tar --create --verbose'
+while creating the archive.  It is because GNU `tar', unless told
+explicitly not to do so, removes some directory prefixes from file
+names before storing them in the archive (*Note absolute::, for more
+information).  In other words, in verbose mode GNU `tar' shows "file
+names" when creating an archive and "member names" when listing it.
+Consider this example:
+
+     $ tar cfv archive /etc/mail
+     tar: Removing leading `/' from member names
+     /etc/mail/
+     /etc/mail/sendmail.cf
+     /etc/mail/aliases
+     $ tar tf archive
+     etc/mail/
+     etc/mail/sendmail.cf
+     etc/mail/aliases
+
+   This default behavior can sometimes be inconvenient.  You can force
+GNU `tar' show member names when creating archive by supplying
+`--show-stored-names' option.
+
+`--show-stored-names'
+     Print member (as opposed to _file_) names when creating the
+     archive.
+
+   You can specify one or more individual member names as arguments when
+using `list'.  In this case, `tar' will only list the names of members
+you identify.  For example, `tar --list --file=afiles.tar apple' would
+only print `apple'.
+
+   Because `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 `tar' that you give the exact member names.  For
+example, `tar --list --file=bfiles.tar birds' would produce an error
+message something like `tar: birds: Not found in archive', because
+there is no member named `birds', only one named `./birds'.  While the
+names `birds' and `./birds' name the same file, _member_ names by
+default are compared verbatim.
+
+   However, `tar --list --file=bfiles.tar baboon' would respond with
+`baboon', because this exact member name is in the archive file
+`bfiles.tar'.  If you are not sure of the exact file name, use
+"globbing patterns", for example:
+
+     $ tar --list --file=bfiles.tar --wildcards '*b*'
+
+will list all members whose name contains `b'.  *Note wildcards::, for
+a detailed discussion of globbing patterns and related `tar' command
+line options.
+
+* Menu:
+
+* list dir::
+
+
+File: tar.info,  Node: list dir,  Up: list
+
+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 `--list'
+(`-t').  To find out file attributes, include the `--verbose' (`-v')
+option.
+
+   For example, to find out about files in the directory `practice', in
+the archive file `music.tar', type:
+
+     $ tar --list --verbose --file=music.tar practice
+
+   `tar' responds:
+
+     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
+
+   When you use a directory name as a file name argument, `tar' acts on
+all the files (including sub-directories) in that directory.
+
+
+File: tar.info,  Node: extract,  Next: going further,  Prev: list,  Up: Tutorial
+
+2.8 How to Extract Members from an Archive
+==========================================
+
+     _(This message will disappear, once this node revised.)_
+
+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 "extraction".  To extract files from
+an archive, use the `--extract' (`--get' or `-x') operation.  As with
+`--create', specify the name of the archive with `--file' (`-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 `--extract', you can extract an entire archive, or specific
+files.  The files can be directories containing other files, or not.  As
+with `--create' (`-c') and `--list' (`-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::
+
+
+File: tar.info,  Node: extracting archives,  Next: extracting files,  Up: extract
+
+2.8.1 Extracting an Entire Archive
+----------------------------------
+
+To extract an entire archive, specify the archive file name only, with
+no individual file names as arguments.  For example,
+
+     $ tar -xvf collection.tar
+
+produces this:
+
+     -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
+
+
+File: tar.info,  Node: extracting files,  Next: extract dir,  Prev: extracting archives,  Up: extract
+
+2.8.2 Extracting Specific Files
+-------------------------------
+
+To extract specific archive members, give their exact member names as
+arguments, as printed by `--list' (`-t').  If you had mistakenly
+deleted one of the files you had placed in the archive `collection.tar'
+earlier (say, `blues'), you can extract it from the archive without
+changing the archive's structure.  Its contents will be identical to
+the original file `blues' that you deleted.
+
+   First, make sure you are in the `practice' directory, and list the
+files in the directory.  Now, delete the file, `blues', and list the
+files in the directory again.
+
+   You can now extract the member `blues' from the archive file
+`collection.tar' like this:
+
+     $ tar --extract --file=collection.tar blues
+
+If you list the files in the directory again, you will see that the file
+`blues' has been restored, with its original permissions, data
+modification times, and owner.(1)  (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 _not_ have been made to the archive
+member.)  The archive file, `collection.tar', is the same as it was
+before you extracted `blues'.  You can confirm this by running `tar'
+with `--list' (`-t').
+
+   Remember that as with other operations, specifying the exact member
+name is important.  `tar --extract --file=bfiles.tar birds' will fail,
+because there is no member named `birds'.  To extract the member named
+`./birds', you must specify `tar --extract --file=bfiles.tar ./birds'.
+If you don't remember the exact member names, use `--list' (`-t') option
+(*note list::).  You can also extract those members that match a
+specific "globbing pattern".  For example, to extract from `bfiles.tar'
+all files that begin with `b', no matter their directory prefix, you
+could type:
+
+     $ tar -x -f bfiles.tar --wildcards --no-anchored 'b*'
+
+Here, `--wildcards' instructs `tar' to treat command line arguments as
+globbing patterns and `--no-anchored' informs it that the patterns
+apply to member names after any `/' delimiter.  The use of globbing
+patterns is discussed in detail in *Note wildcards::.
+
+   You can extract a file to standard output by combining the above
+options with the `--to-stdout' (`-O') option (*note Writing to Standard
+Output::).
+
+   If you give the `--verbose' option, then `--extract' will print the
+names of the archive members as it extracts them.
+
+   ---------- Footnotes ----------
+
+   (1) 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 `umask' is
+compatible with original permissions.
+
+
+File: tar.info,  Node: extract dir,  Next: extracting untrusted archives,  Prev: extracting files,  Up: extract
+
+2.8.3 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 *note
+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, `tar' will create the directory.
+
+   We can demonstrate how to use `--extract' to extract a directory
+file with an example.  Change to the `practice' directory if you
+weren't there, and remove the files `folk' and `jazz'.  Then, go back
+to the parent directory and extract the archive `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 `music.tar'.  To extract only
+the files you deleted, use the following command:
+
+     $ tar -xvf music.tar practice/folk practice/jazz
+     practice/folk
+     practice/jazz
+
+If you were to specify two `--verbose' (`-v') options, `tar' would have
+displayed more detail about the extracted files, as shown in the
+example below:
+
+     $ 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
+
+Because you created the directory with `practice' as part of the file
+names of each of the files by archiving the `practice' directory as
+`practice', you must give `practice' as part of the file names when you
+extract those files from the archive.
+
+
+File: tar.info,  Node: extracting untrusted archives,  Next: failing commands,  Prev: extract dir,  Up: extract
+
+2.8.4 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 `untrusted.tar' came from somewhere else on the
+Internet, and you don't necessarily trust its contents, you can extract
+it as follows:
+
+     $ mkdir newdir
+     $ cd newdir
+     $ tar -xvf ../untrusted.tar
+
+   It is also a good practice to examine contents of the archive before
+extracting it, using `--list' (`-t') option, possibly combined with
+`--verbose' (`-v').
+
+
+File: tar.info,  Node: failing commands,  Prev: extracting untrusted archives,  Up: extract
+
+2.8.5 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,
+
+     $ tar -xvf music.tar folk jazz
+
+you will get the following response:
+
+     tar: folk: Not found in archive
+     tar: jazz: Not found in archive
+     $
+
+This is because these files were not originally _in_ the parent
+directory `..', where the archive is located; they were in the
+`practice' directory, and their file names reflect this:
+
+     $ tar -tvf music.tar
+     practice/folk
+     practice/jazz
+     practice/rock
+
+Likewise, if you try to use this command,
+
+     $ tar -tvf music.tar folk jazz
+
+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 `tar --list --verbose' to list them correctly.
+
+
+File: tar.info,  Node: going further,  Prev: extract,  Up: Tutorial
+
+2.9 Going Further Ahead in this Manual
+======================================
+
+
+File: tar.info,  Node: tar invocation,  Next: operations,  Prev: Tutorial,  Up: Top
+
+3 Invoking GNU `tar'
+********************
+
+     _(This message will disappear, once this node revised.)_
+
+This chapter is about how one invokes the GNU `tar' command, from the
+command synopsis (*note Synopsis::).  There are numerous options, and
+many styles for writing them.  One mandatory option specifies the
+operation `tar' should perform (*note Operation Summary::), other
+options are meant to detail how this operation should be performed
+(*note 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 (*note 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 `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
+`tar' or else, they globally alter the amount of feedback the user
+receives about what is going on.  These are the `--help' and
+`--version' (*note help::), `--verbose' (*note verbose::) and
+`--interactive' options (*note interactive::).
+
+* Menu:
+
+* Synopsis::
+* using tar options::
+* Styles::
+* All Options::
+* help::
+* defaults::
+* verbose::
+* interactive::
+
+
+File: tar.info,  Node: Synopsis,  Next: using tar options,  Up: tar invocation
+
+3.1 General Synopsis of `tar'
+=============================
+
+The GNU `tar' program is invoked as either one of:
+
+     tar OPTION... [NAME]...
+     tar LETTER... [ARGUMENT]... [OPTION]... [NAME]...
+
+   The second form is for when old options are being used.
+
+   You can use `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 `tar', which is called the "operation", specifies which
+action to take.  The other arguments to `tar' are either "options",
+which change the way `tar' performs an operation, or file names or
+archive members, which specify the files or members `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 `tar' main command) is usually given first.
+
+   Each NAME in the synopsis above is interpreted as an archive member
+name when the main command is one of `--compare' (`--diff', `-d'),
+`--delete', `--extract' (`--get', `-x'), `--list' (`-t') or `--update'
+(`-u').  When naming archive members, you must give the exact name of
+the member in the archive, as it is printed by `--list'.  For
+`--append' (`-r') and `--create' (`-c'), these 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 `tar' command.
+
+   `tar' interprets relative file names as being relative to the
+working directory.  `tar' will make all file names relative (by
+removing leading slashes when archiving or restoring files), unless you
+specify otherwise (using the `--absolute-names' option).  *Note
+absolute::, for more information about `--absolute-names'.
+
+   If you give the name of a directory as either a file name or a member
+name, then `tar' acts recursively on all the files and directories
+beneath that directory.  For example, the name `/' identifies all the
+files in the file system to `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.  *Note wildcards::, for more
+information about globbing.  The problem is that shells may only glob
+using existing files in the file system.  Only `tar' itself may glob on
+archive members, so when needed, you must ensure that wildcard
+characters reach `tar' without being interpreted by the shell first.
+Using a backslash before `*' or `?', or putting the whole argument
+between quotes, is usually sufficient for this.
+
+   Even if NAMEs are often specified on the command line, they can also
+be read from a text file in the file system, using the
+`--files-from=FILE-OF-NAMES' (`-T FILE-OF-NAMES') option.
+
+   If you don't use any file name arguments, `--append' (`-r'),
+`--delete' and `--concatenate' (`--catenate', `-A') will do nothing,
+while `--create' (`-c') will usually yield a diagnostic and inhibit
+`tar' execution.  The other operations of `tar' (`--list', `--extract',
+`--compare', and `--update') will act on the entire contents of the
+archive.
+
+   Besides successful exits, GNU `tar' may fail for many reasons.  Some
+reasons correspond to bad usage, that is, when the `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 `tar' has
+completed all its work.  Some errors are such that it would not
+meaningful, or at least risky, to continue processing: `tar' then
+aborts processing immediately.  All abnormal exits, whether immediate
+or delayed, should always be clearly diagnosed on `stderr', after a
+line stating the nature of the error.
+
+   Possible exit codes of GNU `tar' are summarized in the following
+table:
+
+0
+     `Successful termination'.
+
+1
+     `Some files differ'.  If tar was invoked with `--compare'
+     (`--diff', `-d') command line option, this means that some files
+     in the archive differ from their disk counterparts (*note
+     compare::).  If tar was given `--create', `--append' or `--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.
+
+2
+     `Fatal error'.  This means that some fatal, unrecoverable error
+     occurred.
+
+   If `tar' has invoked a subprocess and that subprocess exited with a
+nonzero exit code, `tar' exits with that code as well.  This can
+happen, for example, if `tar' was given some compression option (*note
+gzip::) and the external compressor program failed.  Another example is
+`rmt' failure during backup to the remote device (*note Remote Tape
+Server::).
+
+
+File: tar.info,  Node: using tar options,  Next: Styles,  Prev: Synopsis,  Up: tar invocation
+
+3.2 Using `tar' Options
+=======================
+
+GNU `tar' 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 `tar' program by specifying one, and only
+one operation as an argument to the `tar' command (two lists of four
+operations each may be found at *note frequent operations:: and *note
+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 `tar''s performance by running `tar'
+with one or more options (such as `--verbose' (`-v'), which we used in
+the tutorial).  As we said in the tutorial, "options" are arguments to
+`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 *note All
+Options::.)
+
+   The `TAR_OPTIONS' environment variable specifies default options to
+be placed in front of any explicit options.  For example, if
+`TAR_OPTIONS' is `-v --unlink-first', `tar' behaves as if the two
+options `-v' and `--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 `tar' options are case sensitive.  For example, the
+options `-T' and `-t' are different; the first requires an argument for
+stating the name of a file providing a list of NAMEs, while the second
+does not require an argument and is another way to write `--list'
+(`-t').
+
+   In addition to the eight operations, there are many options to
+`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.
+
+
+File: tar.info,  Node: Styles,  Next: All Options,  Prev: using tar options,  Up: tar invocation
+
+3.3 The Three Option Styles
+===========================
+
+There are three styles for writing operations and options to the command
+line invoking `tar'.  The different styles were developed at different
+times during the history of `tar'.  These styles will be presented
+below, from the most recent to the oldest.
+
+   Some options must take an argument.  (For example, `--file' (`-f'))
+takes the name of an archive file as an argument.  If you do not supply
+an archive file name, `tar' will use a default, but this can be
+confusing; thus, we recommend that you always supply a specific archive
+file name.)  Where you _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 _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
+
+
+File: tar.info,  Node: Long Options,  Next: Short Options,  Up: Styles
+
+3.3.1 Long Option Style
+-----------------------
+
+Each option has at least one "long" (or "mnemonic") name starting with
+two dashes in a row, e.g., `--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 `--compare' and `--diff'.  In addition, long option names can be
+given unique abbreviations.  For example, `--cre' can be used in place
+of `--create' because there is no other long option which begins with
+`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, `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 `tar --help' to see a list of options.  Be aware that if you run
+`tar' with a unique abbreviation for the long name of an option you
+didn't want to use, you are stuck; `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:
+
+     $ tar --create --verbose --blocking-factor=20 --file=/dev/rmt0
+
+gives a fairly good set of hints about what the command does, even for
+those not fully acquainted with `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 `--file' option (which tells the name of
+the `tar' archive) is given a file such as `archive.tar' as argument by
+using any of the following notations: `--file=archive.tar' or `--file
+archive.tar'.
+
+   In contrast, optional arguments must always be introduced using an
+equal sign.  For example, the `--backup' option takes an optional
+argument specifying backup type.  It must be used as
+`--backup=BACKUP-TYPE'.
+
+
+File: tar.info,  Node: Short Options,  Next: Old Options,  Prev: Long Options,  Up: Styles
+
+3.3.2 Short Option Style
+------------------------
+
+Most options also have a "short option" name.  Short options start with
+a single dash, and are followed by a single character, e.g., `-t'
+(which is equivalent to `--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
+`-f archive.tar' or `-farchive.tar' instead of using
+`--file=archive.tar'.  Both `--file=ARCHIVE-NAME' and `-f ARCHIVE-NAME'
+denote the option which indicates a specific archive, here named
+`archive.tar'.
+
+   Short options which take optional arguments take their arguments
+immediately following the option letter, _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., ``tar' -cvf'.  Only the last option in such a set is allowed to
+have an argument(1).
+
+   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:
+
+     $ tar -c -v -b 20 -f /dev/rmt0
+
+   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.
+
+   ---------- Footnotes ----------
+
+   (1) Clustering many options, the last of which has an argument, is a
+rather opaque way to write options.  Some wonder if GNU `getopt' should
+not even be made helpful enough for considering such usages as invalid.
+
+
+File: tar.info,  Node: Old Options,  Next: Mixing,  Prev: Short Options,  Up: Styles
+
+3.3.3 Old Option Style
+----------------------
+
+     _(This message will disappear, once this node revised.)_
+
+Like short options, "old options" are single letters.  However, old
+options must be written together as a single clumped set, without
+spaces separating them or dashes preceding them(1).  This set of
+letters must be the first to appear on the command line, after the
+`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 `t' is
+the same as the short option `-t', and consequently, the same as the
+long option `--list'.  So for example, the command `tar cv' specifies
+the option `-v' in addition to the operation `-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:
+
+     $ tar cvbf 20 /dev/rmt0
+
+Here, `20' is the argument of `-b' and `/dev/rmt0' is the argument of
+`-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 `tar cvbf 20 /dev/rmt0', for example, `20'
+is the argument for `-b', `/dev/rmt0' is the argument for `-f', and
+`-v' does not have a corresponding argument.  Even using short options
+like in `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 `tar' options can surprise even experienced
+users.  For example, the two commands:
+
+     tar cfz archive.tar.gz file
+     tar -cfz archive.tar.gz file
+
+are quite different.  The first example uses `archive.tar.gz' as the
+value for option `f' and recognizes the option `z'.  The second
+example, however, uses `z' as the value for option `f' -- probably not
+what was intended.
+
+   Old options are kept for compatibility with old versions of `tar'.
+
+   This second example could be corrected in many ways, among which the
+following are equivalent:
+
+     tar -czf archive.tar.gz file
+     tar -cf archive.tar.gz -z file
+     tar cf archive.tar.gz -z file
+
+   As far as we know, all `tar' programs, GNU and non-GNU, support old
+options.  GNU `tar' supports them not only for historical reasons, but
+also because many people are used to them.  For compatibility with Unix
+`tar', the first argument is always treated as containing command and
+option letters even if it doesn't start with `-'.  Thus, `tar c' is
+equivalent to `tar -c': both of them specify the `--create' (`-c')
+command to create an archive.
+
+   ---------- Footnotes ----------
+
+   (1) 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.
+
+
+File: tar.info,  Node: Mixing,  Prev: Old Options,  Up: Styles
+
+3.3.4 Mixing Option Styles
+--------------------------
+
+All three styles may be intermixed in a single `tar' command, so long
+as the rules for each style are fully respected(1).  Old style options
+and either of the modern styles of options may be mixed within a single
+`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 `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.
+
+     tar --create --file=archive.tar
+     tar --create -f archive.tar
+     tar --create -farchive.tar
+     tar --file=archive.tar --create
+     tar --file=archive.tar -c
+     tar -c --file=archive.tar
+     tar -c -f archive.tar
+     tar -c -farchive.tar
+     tar -cf archive.tar
+     tar -cfarchive.tar
+     tar -f archive.tar --create
+     tar -f archive.tar -c
+     tar -farchive.tar --create
+     tar -farchive.tar -c
+     tar c --file=archive.tar
+     tar c -f archive.tar
+     tar c -farchive.tar
+     tar cf archive.tar
+     tar f archive.tar --create
+     tar f archive.tar -c
+     tar fc archive.tar
+
+   On the other hand, the following commands are _not_ equivalent to
+the previous set:
+
+     tar -f -c archive.tar
+     tar -fc archive.tar
+     tar -fcarchive.tar
+     tar -farchive.tarc
+     tar cfarchive.tar
+
+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 `tar' archive would be a file named `-c', `c',
+`carchive.tar' or `archive.tarc', respectively.  The first two examples
+also specify a single non-option, NAME argument having the value
+`archive.tar'.  The last example contains only old style option letters
+(repeating option `c' twice), not all of which are meaningful (eg., `.',
+`h', or `i'), with no argument value.
+
+   ---------- Footnotes ----------
+
+   (1) Before GNU `tar' version 1.11.6, a bug prevented intermixing old
+style options with long options in some cases.
+
+
+File: tar.info,  Node: All Options,  Next: help,  Prev: Styles,  Up: tar invocation
+
+3.4 All `tar' Options
+=====================
+
+The coming manual sections contain an alphabetical listing of all `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 `tar' commands in scripts.
+
+* Menu:
+
+* Operation Summary::
+* Option Summary::
+* Short Option Summary::
+
+
+File: tar.info,  Node: Operation Summary,  Next: Option Summary,  Up: All Options
+
+3.4.1 Operations
+----------------
+
+`--append'
+`-r'
+     Appends files to the end of the archive.  *Note append::.
+
+`--catenate'
+`-A'
+     Same as `--concatenate'.  *Note concatenate::.
+
+`--compare'
+`-d'
+     Compares archive members with their counterparts in the file
+     system, and reports differences in file size, mode, owner,
+     modification date and contents.  *Note compare::.
+
+`--concatenate'
+`-A'
+     Appends other `tar' archives to the end of the archive.  *Note
+     concatenate::.
+
+`--create'
+`-c'
+     Creates a new `tar' archive.  *Note create::.
+
+`--delete'
+     Deletes members from the archive.  Don't try this on a archive on a
+     tape!  *Note delete::.
+
+`--diff'
+`-d'
+     Same `--compare'.  *Note compare::.
+
+`--extract'
+`-x'
+     Extracts members from the archive into the file system.  *Note
+     extract::.
+
+`--get'
+`-x'
+     Same as `--extract'.  *Note extract::.
+
+`--list'
+`-t'
+     Lists the members in an archive.  *Note list::.
+
+`--update'
+`-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. *Note update::.
+
+
+
+File: tar.info,  Node: Option Summary,  Next: Short Option Summary,  Prev: Operation Summary,  Up: All Options
+
+3.4.2 `tar' Options
+-------------------
+
+`--absolute-names'
+`-P'
+     Normally when creating an archive, `tar' strips an initial `/'
+     from member names.  This option disables that behavior.  *Note
+     absolute::.
+
+`--after-date'
+     (See `--newer', *note after::)
+
+`--anchored'
+     A pattern must match an initial subsequence of the name's
+     components.  *Note controlling pattern-matching::.
+
+`--atime-preserve'
+`--atime-preserve=replace'
+`--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.
+
+     `--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 `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.
+
+     `--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 `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 `tar' knows that it does not work, and if you use
+     `--atime-preserve=system' then `tar' complains and exits right
+     away.  But other times `tar' might think that the option works
+     when it actually does not.
+
+     Currently `--atime-preserve' with no operand defaults to
+     `--atime-preserve=replace', but this may change in the future as
+     support for `--atime-preserve=system' improves.
+
+     If your operating system does not support
+     `--atime-preserve=system', you might be able to preserve access
+     times reliably by by using the `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 `noatime' mount option
+     available on some systems.  However, mounting typically requires
+     superuser privileges and can be a pain to manage.
+
+`--backup=BACKUP-TYPE'
+     Rather than deleting files from the file system, `tar' will back
+     them up using simple or numbered backups, depending upon
+     BACKUP-TYPE.  *Note backup::.
+
+`--block-number'
+`-R'
+     With this option present, `tar' prints error messages for read
+     errors with the block number in the archive file.  *Note
+     block-number::.
+
+`--blocking-factor=BLOCKING'
+`-b BLOCKING'
+     Sets the blocking factor `tar' uses to BLOCKING x 512 bytes per
+     record.  *Note Blocking Factor::.
+
+`--bzip2'
+`-j'
+     This option tells `tar' to read or write archives through `bzip2'.
+     *Note gzip::.
+
+`--checkpoint[=NUMBER]'
+     This option directs `tar' to print periodic checkpoint messages as
+     it reads through the archive.  It is intended for when you want a
+     visual indication that `tar' is still running, but don't want to
+     see `--verbose' output.  For a detailed description, see *note
+     Progress information::.
+
+`--check-links'
+`-l'
+     If this option was given, `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 (1).
+
+`--compress'
+`--uncompress'
+`-Z'
+     `tar' will use the `compress' program when reading or writing the
+     archive.  This allows you to directly act on archives while saving
+     space.  *Note gzip::.
+
+`--confirmation'
+     (See `--interactive'.)  *Note interactive::.
+
+`--delay-directory-restore'
+     Delay setting modification times and permissions of extracted
+     directories until the end of extraction. *Note Directory
+     Modification Times and Permissions::.
+
+`--dereference'
+`-h'
+     When creating a `tar' archive, `tar' will archive the file that a
+     symbolic link points to, rather than archiving the symlink.  *Note
+     dereference::.
+
+`--directory=DIR'
+`-C DIR'
+     When this option is specified, `tar' will change its current
+     directory to DIR before performing any operations.  When this
+     option is used during archive creation, it is order sensitive.
+     *Note directory::.
+
+`--exclude=PATTERN'
+     When performing operations, `tar' will skip files that match
+     PATTERN.  *Note exclude::.
+
+`--exclude-from=FILE'
+`-X FILE'
+     Similar to `--exclude', except `tar' will use the list of patterns
+     in the file FILE.  *Note exclude::.
+
+`--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.
+
+     *Note exclude::.
+
+`--exclude-caches-under'
+     Exclude from dump any directory containing a valid cache directory
+     tag file, but still dump the directory node itself.
+
+     *Note exclude::.
+
+`--exclude-caches-all'
+     Exclude from dump any directory containing a valid cache directory
+     tag file.  *Note exclude::.
+
+`--exclude-tag=FILE'
+     Exclude from dump any directory containing file named FILE, but
+     dump the directory node and FILE itself.  *Note exclude::.
+
+`--exclude-tag-under=FILE'
+     Exclude from dump the contents of any directory containing file
+     named FILE, but dump the directory node itself.  *Note exclude::.
+
+`--exclude-tag-all=FILE'
+     Exclude from dump any directory containing file named FILE.  *Note
+     exclude::.
+
+`--file=ARCHIVE'
+`-f ARCHIVE'
+     `tar' will use the file ARCHIVE as the `tar' archive it performs
+     operations on, rather than `tar''s compilation dependent default.
+     *Note file tutorial::.
+
+`--files-from=FILE'
+`-T FILE'
+     `tar' will use the contents of FILE as a list of archive members
+     or files to operate on, in addition to those specified on the
+     command-line.  *Note files::.
+
+`--force-local'
+     Forces `tar' to interpret the file name given to `--file' as a
+     local file, even if it looks like a remote tape drive name.  *Note
+     local and remote archives::.
+
+`--format=FORMAT'
+`-H FORMAT'
+     Selects output archive format.  FORMAT may be one of the following:
+
+    `v7'
+          Creates an archive that is compatible with Unix V7 `tar'.
+
+    `oldgnu'
+          Creates an archive that is compatible with GNU `tar' version
+          1.12 or earlier.
+
+    `gnu'
+          Creates archive in GNU tar 1.13 format.  Basically it is the
+          same as `oldgnu' with the only difference in the way it
+          handles long numeric fields.
+
+    `ustar'
+          Creates a POSIX.1-1988 compatible archive.
+
+    `posix'
+          Creates a POSIX.1-2001 archive.
+
+
+     *Note Formats::, for a detailed discussion of these formats.
+
+`--group=GROUP'
+     Files added to the `tar' archive will have a group ID of GROUP,
+     rather than the group from the source file.  GROUP is first decoded
+     as a group symbolic name, but if this interpretation fails, it has
+     to be a decimal numeric group ID.  *Note override::.
+
+     Also see the comments for the `--owner=USER' option.
+
+`--gzip'
+`--gunzip'
+`--ungzip'
+`-z'
+     This option tells `tar' to read or write archives through `gzip',
+     allowing `tar' to directly operate on several kinds of compressed
+     archives transparently.  *Note gzip::.
+
+`--help'
+`-?'
+     `tar' will print out a short message summarizing the operations and
+     options to `tar' and exit. *Note help::.
+
+`--ignore-case'
+     Ignore case when matching member or file names with patterns.
+     *Note controlling pattern-matching::.
+
+`--ignore-command-error'
+     Ignore exit codes of subprocesses. *Note Writing to an External
+     Program::.
+
+`--ignore-failed-read'
+     Do not exit unsuccessfully merely because an unreadable file was
+     encountered.  *Note Reading::.
+
+`--ignore-zeros'
+`-i'
+     With this option, `tar' will ignore zeroed blocks in the archive,
+     which normally signals EOF.  *Note Reading::.
+
+`--incremental'
+`-G'
+     Informs `tar' that it is working with an old GNU-format
+     incremental backup archive.  It is intended primarily for
+     backwards compatibility only.  *Note Incremental Dumps::, for a
+     detailed discussion of incremental archives.
+
+`--index-file=FILE'
+     Send verbose output to FILE instead of to standard output.
+
+`--info-script=SCRIPT-FILE'
+`--new-volume-script=SCRIPT-FILE'
+`-F SCRIPT-FILE'
+     When `tar' is performing multi-tape backups, SCRIPT-FILE is run at
+     the end of each tape.  If SCRIPT-FILE exits with nonzero status,
+     `tar' fails immediately.  *Note info-script::, for a detailed
+     discussion of SCRIPT-FILE.
+
+`--interactive'
+`--confirmation'
+`-w'
+     Specifies that `tar' should ask the user for confirmation before
+     performing potentially destructive options, such as overwriting
+     files.  *Note interactive::.
+
+`--keep-newer-files'
+     Do not replace existing files that are newer than their archive
+     copies when extracting files from an archive.
+
+`--keep-old-files'
+`-k'
+     Do not overwrite existing files when extracting files from an
+     archive.  *Note Keep Old Files::.
+
+`--label=NAME'
+`-V NAME'
+     When creating an archive, instructs `tar' to write NAME as a name
+     record in the archive.  When extracting or listing archives, `tar'
+     will only operate on archives that have a label matching the
+     pattern specified in NAME.  *Note Tape Files::.
+
+`--listed-incremental=SNAPSHOT-FILE'
+`-g SNAPSHOT-FILE'
+     During a `--create' operation, specifies that the archive that
+     `tar' creates is a new GNU-format incremental backup, using
+     SNAPSHOT-FILE to determine which files to backup.  With other
+     operations, informs `tar' that the archive is in incremental
+     format.  *Note Incremental Dumps::.
+
+`--mode=PERMISSIONS'
+     When adding files to an archive, `tar' will use PERMISSIONS for
+     the archive members, rather than the permissions from the files.
+     PERMISSIONS can be specified either as an octal number or as
+     symbolic permissions, like with `chmod'. *Note override::.
+
+`--mtime=DATE'
+     When adding files to an archive, `tar' will use DATE as the
+     modification time of members when creating archives, instead of
+     their actual modification times.  The value of DATE can be either
+     a textual date representation (*note Date input formats::) or a
+     name of the existing file, starting with `/' or `.'.  In the
+     latter case, the modification time of that file is used. *Note
+     override::.
+
+`--multi-volume'
+`-M'
+     Informs `tar' that it should create or otherwise operate on a
+     multi-volume `tar' archive.  *Note Using Multiple Tapes::.
+
+`--new-volume-script'
+     (see -info-script)
+
+`--newer=DATE'
+`--after-date=DATE'
+`-N'
+     When creating an archive, `tar' will only add files that have
+     changed since DATE.  If DATE begins with `/' or `.', it is taken
+     to be the name of a file whose data modification time specifies
+     the date.  *Note after::.
+
+`--newer-mtime=DATE'
+     Like `--newer', but add only files whose contents have changed (as
+     opposed to just `--newer', which will also back up files for which
+     any status information has changed).  *Note after::.
+
+`--no-anchored'
+     An exclude pattern can match any subsequence of the name's
+     components.  *Note controlling pattern-matching::.
+
+`--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.  *Note Directory Modification Times and
+     Permissions::.
+
+`--no-ignore-case'
+     Use case-sensitive matching.  *Note controlling pattern-matching::.
+
+`--no-ignore-command-error'
+     Print warnings about subprocesses that terminated with a nonzero
+     exit code. *Note Writing to an External Program::.
+
+`--no-overwrite-dir'
+     Preserve metadata of existing directories when extracting files
+     from an archive.  *Note Overwrite Old Files::.
+
+`--no-quote-chars=STRING'
+     Remove characters listed in STRING from the list of quoted
+     characters set by the previous `--quote-chars' option (*note
+     quoting styles::).
+
+`--no-recursion'
+     With this option, `tar' will not recurse into directories.  *Note
+     recurse::.
+
+`--no-same-owner'
+`-o'
+     When extracting an archive, do not attempt to preserve the owner
+     specified in the `tar' archive.  This the default behavior for
+     ordinary users.
+
+`--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.
+
+`--no-unquote'
+     Treat all input file or member names literally, do not interpret
+     escape sequences.  *Note input name quoting::.
+
+`--no-wildcards'
+     Do not use wildcards.  *Note controlling pattern-matching::.
+
+`--no-wildcards-match-slash'
+     Wildcards do not match `/'.  *Note controlling pattern-matching::.
+
+`--null'
+     When `tar' is using the `--files-from' option, this option
+     instructs `tar' to expect file names terminated with NUL, so `tar'
+     can correctly work with file names that contain newlines.  *Note
+     nul::.
+
+`--numeric-owner'
+     This option will notify `tar' that it should use numeric user and
+     group IDs when creating a `tar' file, rather than names.  *Note
+     Attributes::.
+
+`-o'
+     The function of this option depends on the action `tar' is
+     performing.  When extracting files, `-o' is a synonym for
+     `--no-same-owner', i.e., it prevents `tar' from restoring
+     ownership of files being extracted.
+
+     When creating an archive, it is a synonym for `--old-archive'.
+     This behavior is for compatibility with previous versions of GNU
+     `tar', and will be removed in future releases.
+
+     *Note Changes::, for more information.
+
+`--occurrence[=NUMBER]'
+     This option can be used in conjunction with one of the subcommands
+     `--delete', `--diff', `--extract' or `--list' when a list of files
+     is given either on the command line or via `-T' option.
+
+     This option instructs `tar' to process only the NUMBERth
+     occurrence of each named file.  NUMBER defaults to 1, so
+
+          tar -x -f archive.tar --occurrence filename
+
+     will extract the first occurrence of the member `filename' from
+     `archive.tar' and will terminate without scanning to the end of
+     the archive.
+
+`--old-archive'
+     Synonym for `--format=v7'.
+
+`--one-file-system'
+     Used when creating an archive.  Prevents `tar' from recursing into
+     directories that are on different file systems from the current
+     directory (2).
+
+`--overwrite'
+     Overwrite existing files and directory metadata when extracting
+     files from an archive.  *Note Overwrite Old Files::.
+
+`--overwrite-dir'
+     Overwrite the metadata of existing directories when extracting
+     files from an archive.  *Note Overwrite Old Files::.
+
+`--owner=USER'
+     Specifies that `tar' should use USER as the owner of members when
+     creating archives, instead of the user associated with the source
+     file.  USER is first decoded as a user symbolic name, but if this
+     interpretation fails, it has to be a decimal numeric user ID.
+     *Note override::.
+
+     This option does not affect extraction from archives.
+
+`--pax-option=KEYWORD-LIST'
+     This option is meaningful only with POSIX.1-2001 archives (*note
+     posix::).  It modifies the way `tar' handles the extended header
+     keywords.  KEYWORD-LIST is a comma-separated list of keyword
+     options.  *Note PAX keywords::, for a detailed discussion.
+
+`--portability'
+`--old-archive'
+     Synonym for `--format=v7'.
+
+`--posix'
+     Same as `--format=posix'.
+
+`--preserve'
+     Synonymous with specifying both `--preserve-permissions' and
+     `--same-order'.  *Note Setting Access Permissions::.
+
+`--preserve-order'
+     (See `--same-order'; *note Reading::.)
+
+`--preserve-permissions'
+`--same-permissions'
+`-p'
+     When `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 `tar' that it should use the
+     permissions directly from the archive.  *Note Setting Access
+     Permissions::.
+
+`--quote-chars=STRING'
+     Always quote characters from STRING, even if the selected quoting
+     style would not quote them (*note quoting styles::).
+
+`--quoting-style=STYLE'
+     Set quoting style to use when printing member and file names
+     (*note quoting styles::). Valid STYLE values are: `literal',
+     `shell', `shell-always', `c', `escape', `locale', and `clocale'.
+     Default quoting style is `escape', unless overridden while
+     configuring the package.
+
+`--read-full-records'
+`-B'
+     Specifies that `tar' should reblock its input, for reading from
+     pipes on systems with buggy implementations.  *Note Reading::.
+
+`--record-size=SIZE'
+     Instructs `tar' to use SIZE bytes per record when accessing the
+     archive.  *Note Blocking Factor::.
+
+`--recursion'
+     With this option, `tar' recurses into directories (default).
+     *Note recurse::.
+
+`--recursive-unlink'
+     Remove existing directory hierarchies before extracting
+     directories of the same name from the archive.  *Note Recursive
+     Unlink::.
+
+`--remove-files'
+     Directs `tar' to remove the source file from the file system after
+     appending it to an archive.  *Note remove files::.
+
+`--restrict'
+     Disable use of some potentially harmful `tar' options.  Currently
+     this option disables shell invocation from multi-volume menu
+     (*note Using Multiple Tapes::).
+
+`--rmt-command=CMD'
+     Notifies `tar' that it should use CMD instead of the default
+     `/usr/libexec/rmt' (*note Remote Tape Server::).
+
+`--rsh-command=CMD'
+     Notifies `tar' that is should use CMD to communicate with remote
+     devices.  *Note Device::.
+
+`--same-order'
+`--preserve-order'
+`-s'
+     This option is an optimization for `tar' when running on machines
+     with small amounts of memory.  It informs `tar' that the list of
+     file arguments has already been sorted to match the order of files
+     in the archive.  *Note Reading::.
+
+`--same-owner'
+     When extracting an archive, `tar' will attempt to preserve the
+     owner specified in the `tar' archive with this option present.
+     This is the default behavior for the superuser; this option has an
+     effect only for ordinary users.  *Note Attributes::.
+
+`--same-permissions'
+     (See `--preserve-permissions'; *note Setting Access Permissions::.)
+
+`--seek'
+`-n'
+     Assume that the archive media supports seeks to arbitrary
+     locations.  Usually `tar' determines automatically whether the
+     archive can be seeked or not.  This option is intended for use in
+     cases when such recognition fails.
+
+`--show-defaults'
+     Displays the default options used by `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:
+
+          $ tar --show-defaults
+          --format=gnu -f- -b20 --quoting-style=escape \
+          --rmt-command=/usr/libexec/rmt --rsh-command=/usr/bin/rsh
+
+`--show-omitted-dirs'
+     Instructs `tar' to mention the directories it is skipping when
+     operating on a `tar' archive.  *Note show-omitted-dirs::.
+
+`--show-transformed-names'
+`--show-stored-names'
+     Display file or member names after applying any transformations
+     (*note transform::).  In particular, when used in conjunction with
+     one of the archive creation operations it instructs `tar' to list
+     the member names stored in the archive, as opposed to the actual
+     file names.  *Note listing member and file names::.
+
+`--sparse'
+`-S'
+     Invokes a GNU extension when adding files to an archive that
+     handles sparse files efficiently.  *Note sparse::.
+
+`--sparse-version=VERSION'
+     Specifies the "format version" to use when archiving sparse files.
+     Implies `--sparse'.  *Note sparse::. For the description of the
+     supported sparse formats, *Note Sparse Formats::.
+
+`--starting-file=NAME'
+`-K NAME'
+     This option affects extraction only; `tar' will skip extracting
+     files in the archive until it finds one that matches NAME.  *Note
+     Scarce::.
+
+`--strip-components=NUMBER'
+     Strip given NUMBER of leading components from file names before
+     extraction.  For example, if archive `archive.tar' contained
+     `/some/file/name', then running
+
+          tar --extract --file archive.tar --strip-components=2
+
+     would extract this file to file `name'.
+
+     , summary
+
+`--suffix=SUFFIX'
+     Alters the suffix `tar' uses when backing up files from the default
+     `~'.  *Note backup::.
+
+`--tape-length=NUM'
+`-L NUM'
+     Specifies the length of tapes that `tar' is writing as being
+     NUM x 1024 bytes long.  *Note Using Multiple Tapes::.
+
+`--test-label'
+     Reads the volume label.  If an argument is specified, test whether
+     it matches the volume label.  *Note --test-label option::.
+
+`--to-command=COMMAND'
+     During extraction `tar' will pipe extracted files to the standard
+     input of COMMAND.  *Note Writing to an External Program::.
+
+`--to-stdout'
+`-O'
+     During extraction, `tar' will extract files to stdout rather than
+     to the file system.  *Note Writing to Standard Output::.
+
+`--totals[=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 SIGNO is delivered to `tar'.  *Note totals::.
+
+`--touch'
+`-m'
+     Sets the data modification time of extracted files to the
+     extraction time, rather than the data modification time stored in
+     the archive.  *Note Data Modification Times::.
+
+`--transform=SED-EXPR'
+     Transform file or member names using `sed' replacement expression
+     SED-EXPR.  For example,
+
+          $ tar cf archive.tar --transform 's,^\./,usr/,' .
+
+     will add to `archive' files from the current working directory,
+     replacing initial `./' prefix with `usr/'. For the detailed
+     discussion, *Note transform::.
+
+     To see transformed member names in verbose listings, use
+     `--show-transformed-names' option (*note show-transformed-names::).
+
+`--uncompress'
+     (See `--compress'. *note gzip::)
+
+`--ungzip'
+     (See `--gzip'. *note gzip::)
+
+`--unlink-first'
+`-U'
+     Directs `tar' to remove the corresponding file from the file
+     system before extracting it from the archive.  *Note Unlink
+     First::.
+
+`--unquote'
+     Enable unquoting input file or member names (default).  *Note
+     input name quoting::.
+
+`--use-compress-program=PROG'
+     Instructs `tar' to access the archive through PROG, which is
+     presumed to be a compression program of some sort.  *Note gzip::.
+
+`--utc'
+     Display file modification dates in UTC.  This option implies
+     `--verbose'.
+
+`--verbose'
+`-v'
+     Specifies that `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.
+     *Note verbose::.
+
+`--verify'
+`-W'
+     Verifies that the archive was correctly written when creating an
+     archive.  *Note verify::.
+
+`--version'
+     Print information about the program's name, version, origin and
+     legal status, all on standard output, and then exit successfully.
+     *Note help::.
+
+`--volno-file=FILE'
+     Used in conjunction with `--multi-volume'.  `tar' will keep track
+     of which volume of a multi-volume archive it is working in FILE.
+     *Note volno-file::.
+
+`--wildcards'
+     Use wildcards when matching member names with patterns.  *Note
+     controlling pattern-matching::.
+
+`--wildcards-match-slash'
+     Wildcards match `/'.  *Note controlling pattern-matching::.
+
+   ---------- Footnotes ----------
+
+   (1) Earlier versions of GNU `tar' understood `-l' as a synonym for
+`--one-file-system'.  The current semantics, which complies to UNIX98,
+was introduced with version 1.15.91. *Note Changes::, for more
+information.
+
+   (2) Earlier versions of GNU `tar' understood `-l' as a synonym for
+`--one-file-system'.  This has changed in version 1.15.91. *Note
+Changes::, for more information.
+
+
+File: tar.info,  Node: Short Option Summary,  Prev: Option Summary,  Up: All Options
+
+3.4.3 Short Options Cross Reference
+-----------------------------------
+
+Here is an alphabetized list of all of the short option forms, matching
+them with the equivalent long option.
+
+Short Option   Reference
+-------------------------------------------------------------------------- 
+-A             *note --concatenate::.
+-B             *note --read-full-records::.
+-C             *note --directory::.
+-F             *note --info-script::.
+-G             *note --incremental::.
+-K             *note --starting-file::.
+-L             *note --tape-length::.
+-M             *note --multi-volume::.
+-N             *note --newer::.
+-O             *note --to-stdout::.
+-P             *note --absolute-names::.
+-R             *note --block-number::.
+-S             *note --sparse::.
+-T             *note --files-from::.
+-U             *note --unlink-first::.
+-V             *note --label::.
+-W             *note --verify::.
+-X             *note --exclude-from::.
+-Z             *note --compress::.
+-b             *note --blocking-factor::.
+-c             *note --create::.
+-d             *note --compare::.
+-f             *note --file::.
+-g             *note --listed-incremental::.
+-h             *note --dereference::.
+-i             *note --ignore-zeros::.
+-j             *note --bzip2::.
+-k             *note --keep-old-files::.
+-l             *note --check-links::.
+-m             *note --touch::.
+-o             When creating, *note --no-same-owner::, when extracting --
+               *note --portability::.
+               
+                  The later usage is deprecated.  It is retained for
+               compatibility with the earlier versions of GNU `tar'.  In
+               future releases `-o' will be equivalent to
+               `--no-same-owner' only.
+-p             *note --preserve-permissions::.
+-r             *note --append::.
+-s             *note --same-order::.
+-t             *note --list::.
+-u             *note --update::.
+-v             *note --verbose::.
+-w             *note --interactive::.
+-x             *note --extract::.
+-z             *note --gzip::.
+
+
+File: tar.info,  Node: help,  Next: defaults,  Prev: All Options,  Up: tar invocation
+
+3.5 GNU `tar' documentation
+===========================
+
+Being careful, the first thing is really checking that you are using
+GNU `tar', indeed.  The `--version' option causes `tar' to print
+information about its name, version, origin and legal status, all on
+standard output, and then exit successfully.  For example,
+`tar --version' might print:
+
+     tar (GNU tar) 1.17
+     Copyright (C) 2006 Free Software Foundation, Inc.
+     This is free software.  You may redistribute copies of it under the terms
+     of the GNU General Public License <http://www.gnu.org/licenses/gpl.html>.
+     There is NO WARRANTY, to the extent permitted by law.
+
+     Written by John Gilmore and Jay Fenlason.
+
+The first occurrence of `tar' in the result above is the program name
+in the package (for example, `rmt' is another program), while the
+second occurrence of `tar' is the name of the package itself,
+containing possibly many programs.  The package is currently named
+`tar', after the name of the main program it contains(1).
+
+   Another thing you might want to do is checking the spelling or
+meaning of some particular `tar' option, without resorting to this
+manual, for once you have carefully read it.  GNU `tar' has a short
+help feature, triggerable through the `--help' option.  By using this
+option, `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:
+
+     $ tar --help | less
+
+presuming, here, that you like using `less' for a pager.  Other popular
+pagers are `more' and `pg'.  If you know about some KEYWORD which
+interests you and do not want to read all the `--help' output, another
+common idiom is doing:
+
+     tar --help | grep KEYWORD
+
+for getting only the pertinent lines.  Notice, however, that some `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 `tar --help' is
+configurable. *Note Configuring Help Summary::, for a detailed
+description.
+
+   If you only wish to check the spelling of an option, running `tar
+--usage' may be a better choice.  This will display a terse list of
+`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 `tar' manual in some form.  This
+manual is available in a variety of forms from
+`http://www.gnu.org/software/tar/manual'.  It may be printed out of the
+GNU `tar' distribution, provided you have TeX already installed
+somewhere, and a laser printer around.  Just configure the
+distribution, execute the command `make dvi', then print `doc/tar.dvi'
+the usual way (contact your local guru to know how).  If GNU `tar' has
+been conveniently installed at your place, this manual is also
+available in interactive, hypertextual form as an Info file.  Just call
+`info tar' or, if you do not have the `info' program handy, use the
+Info reader provided within GNU Emacs, calling `tar' from the main Info
+menu.
+
+   There is currently no `man' page for GNU `tar'.  If you observe such
+a `man' page on the system you are running, either it does not belong
+to GNU `tar', or it has not been produced by GNU.  Some package
+maintainers convert `tar --help' output to a man page, using
+`help2man'.  In any case, please bear in mind that the authoritative
+source of information about GNU `tar' is this Texinfo documentation.
+
+   ---------- Footnotes ----------
+
+   (1) There are plans to merge the `cpio' and `tar' packages into a
+single one which would be called `paxutils'.  So, who knows if, one of
+this days, the `--version' would not output `tar (GNU paxutils) 3.2'
+
+
+File: tar.info,  Node: defaults,  Next: verbose,  Prev: help,  Up: tar invocation
+
+3.6 Obtaining GNU `tar' default values
+======================================
+
+GNU `tar' has some predefined defaults that are used when you do not
+explicitly specify another values.  To obtain a list of such defaults,
+use `--show-defaults' option.  This will output the values in the form
+of `tar' command line options:
+
+     tar --show-defaults
+     --format=gnu -f- -b20 --quoting-style=escape
+     --rmt-command=/etc/rmt --rsh-command=/usr/bin/rsh
+
+Notice, that this option outputs only one line.  The example output
+above has been split to fit page boundaries.
+
+The above output shows that this version of GNU `tar' defaults to using
+`gnu' archive format (*note Formats::), it uses standard output as the
+archive, if no `--file' option has been given (*note file tutorial::),
+the default blocking factor is 20 (*note Blocking Factor::).  It also
+shows the default locations where `tar' will look for `rmt' and `rsh'
+binaries.
+
+
+File: tar.info,  Node: verbose,  Next: interactive,  Prev: defaults,  Up: tar invocation
+
+3.7 Checking `tar' progress
+===========================
+
+Typically, `tar' performs most operations without reporting any
+information to the user except error messages.  When using `tar' with
+many options, particularly ones with complicated or
+difficult-to-predict behavior, it is possible to make serious mistakes.
+`tar' provides several options that make observing `tar' easier.  These
+options cause `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.
+
+   Normally, the `--list' (`-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 `--verbose' (`-v') option causes `tar'
+to print the name of each file or archive member as it is processed.
+This and the other options which make `tar' print status information
+can be useful in monitoring `tar'.
+
+   With `--create' or `--extract', `--verbose' used once just prints
+the names of the files or members as they are processed.  Using it
+twice causes `tar' to print a longer listing (*Note verbose member
+listing::, for the description) for each member.  Since `--list'
+already prints  the names of the members, `--verbose' used once with
+`--list' causes `tar' to print an `ls -l' type listing of the files in
+the archive.  The following examples both extract members with long
+list output:
+
+     $ tar --extract --file=archive.tar --verbose --verbose
+     $ tar xvvf archive.tar
+
+   Verbose output appears on the standard output except when an archive
+is being written to the standard output, as with `tar --create --file=-
+--verbose' (`tar cfv -', or even `tar cv'--if the installer let
+standard output be the default archive).  In that case `tar' writes
+verbose output to the standard error stream.
+
+   If `--index-file=FILE' is specified, `tar' sends verbose output to
+FILE rather than to standard output or standard error.
+
+   The `--totals' option causes `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.:
+
+     $ tar -c -f archive.tar --totals /home
+     Total bytes written: 7924664320 (7.4GiB, 85MiB/s)
+
+   When reading an archive, this option displays the number of bytes
+read:
+
+     $ tar -x -f archive.tar --totals
+     Total bytes read: 7924664320 (7.4GiB, 95MiB/s)
+
+   Finally, when deleting from an archive, the `--totals' option
+displays both numbers plus number of bytes removed from the archive:
+
+     $ 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
+
+   You can also obtain this information on request.  When `--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:
+
+`--totals=SIGNO'
+     Print statistics upon delivery of signal SIGNO.  Valid arguments
+     are: `SIGHUP', `SIGQUIT', `SIGINT', `SIGUSR1' and `SIGUSR2'.
+     Shortened names without `SIG' prefix are also accepted.
+
+   Both forms of `--totals' option can be used simultaneously.  Thus,
+`tar -x --totals --totals=USR1' instructs `tar' to extract all members
+from its default archive and print statistics after finishing the
+extraction, as well as when receiving signal `SIGUSR1'.
+
+   The `--checkpoint' option prints an occasional message as `tar'
+reads or writes the archive.  It is designed for those who don't need
+the more detailed (and voluminous) output of `--block-number' (`-R'),
+but do want visual confirmation that `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:
+
+     $ tar -c --checkpoint=1000 /var
+     tar: Write checkpoint 1000
+     tar: Write checkpoint 2000
+     tar: Write checkpoint 3000
+
+   This example shows the default checkpoint message used by `tar'.  If
+you place a dot immediately after the equal sign, it will print a `.'
+at each checkpoint.  For example:
+
+     $ tar -c --checkpoint=.1000 /var
+     ...
+
+   The `--show-omitted-dirs' option, when reading an archive--with
+`--list' or `--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 `--exclude=PATTERN' option, or some other
+reason.
+
+   If `--block-number' (`-R') is used, `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
+`--block-number' (`-R') is used.  Note that GNU `tar' drains the
+archive before exiting when reading the archive from a pipe.
+
+   This option is especially useful when reading damaged archives, since
+it helps pinpoint the damaged sections.  It can also be used with
+`--list' (`-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).  *Note backup::.
+
+
+File: tar.info,  Node: interactive,  Prev: verbose,  Up: tar invocation
+
+3.8 Asking for Confirmation During Operations
+=============================================
+
+Typically, `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 (*note Choosing::), or by performing an operation
+interactively, using the `--interactive' (`-w') option.  `tar' also
+accepts `--confirmation' for this option.
+
+   When the `--interactive' (`-w') option is specified, before reading,
+writing, or deleting files, `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 `y'.  If your input line begins with anything other than `y',
+`tar' skips that file.
+
+   If `tar' is reading the archive from the standard input, `tar' opens
+the 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 `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.
+
+
+File: tar.info,  Node: operations,  Next: Backups,  Prev: tar invocation,  Up: Top
+
+4 GNU `tar' Operations
+**********************
+
+* Menu:
+
+* Basic tar::
+* Advanced tar::
+* create options::
+* extract options::
+* backup::
+* Applications::
+* looking ahead::
+
+
+File: tar.info,  Node: Basic tar,  Next: Advanced tar,  Up: operations
+
+4.1 Basic GNU `tar' Operations
+==============================
+
+The basic `tar' operations, `--create' (`-c'), `--list' (`-t') and
+`--extract' (`--get', `-x'), are currently presented and described in
+the tutorial chapter of this manual.  This section provides some
+complementary notes for these operations.
+
+`--create'
+`-c'
+     Creating an empty archive would have some kind of elegance.  One
+     can initialize an empty archive and later use `--append' (`-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 `tar' to destroy a magnetic tape with an empty
+     archive(1).  The two most common errors are:
+
+       1. Mistakingly using `create' instead of `extract', when the
+          intent was to extract the full contents of an archive.  This
+          error is likely: keys `c' and `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
+          "exploding" an archive, they usually mean something else :-).
+
+       2. Forgetting the argument to `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 `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.
+
+     So, recognizing the likelihood and the catastrophic nature of these
+     errors, GNU `tar' now takes some distance from elegance, and
+     cowardly refuses to create an archive when `--create' option is
+     given, there are no arguments besides options, and `--files-from'
+     (`-T') option is _not_ used.  To get around the cautiousness of
+     GNU `tar' and nevertheless create an archive with nothing in it,
+     one may still use, as the value for the `--files-from' option, a
+     file with no names in it, as shown in the following commands:
+
+          tar --create --file=empty-archive.tar --files-from=/dev/null
+          tar cfT empty-archive.tar /dev/null
+
+`--extract'
+`--get'
+`-x'
+     A socket is stored, within a GNU `tar' archive, as a pipe.
+
+``--list' (`-t')'
+     GNU `tar' now shows dates as `1996-08-30', while it used to show
+     them as `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 `http://www.cl.cam.ac.uk/~mgk25/iso-time.html' if you are
+     curious, it contains a detailed explanation of the ISO 8601
+     standard.
+
+
+   ---------- Footnotes ----------
+
+   (1) This is well described in `Unix-haters Handbook', by Simson
+Garfinkel, Daniel Weise & Steven Strassmann, IDG Books, ISBN
+1-56884-203-1.
+
+
+File: tar.info,  Node: Advanced tar,  Next: create options,  Prev: Basic tar,  Up: operations
+
+4.2 Advanced GNU `tar' Operations
+=================================
+
+Now that you have learned the basics of using GNU `tar', you may want
+to learn about further ways in which `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 `tar'
+commands.  Additionally, this chapter includes options which allow you
+to define the output from `tar' more carefully, and provide help and
+error correction in special circumstances.
+
+* Menu:
+
+* Operations::
+* append::
+* update::
+* concatenate::
+* delete::
+* compare::
+
+
+File: tar.info,  Node: Operations,  Next: append,  Up: Advanced tar
+
+4.2.1 The Five Advanced `tar' Operations
+----------------------------------------
+
+     _(This message will disappear, once this node revised.)_
+
+In the last chapter, you learned about the first three operations to
+`tar'.  This chapter presents the remaining five operations to `tar':
+`--append', `--update', `--concatenate', `--delete', and `--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
+`practice', the files are `jazz', `blues', `folk', `rock', and the two
+archive files you created are `collection.tar' and `music.tar'.
+
+   We will also use the archive files `afiles.tar' and `bfiles.tar'.
+The archive `afiles.tar' contains the members `apple', `angst', and
+`aspic'; `bfiles.tar' contains the members `./birds', `baboon', and
+`./box'.
+
+   Unless we state otherwise, all practicing you do and examples you
+follow in this chapter will take place in the `practice' directory that
+you created in the previous chapter; see *note 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:
+
+`--append'
+`-r'
+     Add new entries to an archive that already exists.
+
+`--update'
+`-r'
+     Add more recent copies of archive members to the end of an
+     archive, if they exist.
+
+`--concatenate'
+`--catenate'
+`-A'
+     Add one or more pre-existing archives to the end of another
+     archive.
+
+`--delete'
+     Delete items from an archive (does not work on tapes).
+
+`--compare'
+`--diff'
+`-d'
+     Compare archive members to their counterparts in the file system.
+
+
+File: tar.info,  Node: append,  Next: update,  Prev: Operations,  Up: Advanced tar
+
+4.2.2 How to Add Files to Existing Archives: `--append'
+-------------------------------------------------------
+
+     _(This message will disappear, once this node revised.)_
+
+If you want to add files to an existing archive, you don't need to
+create a new archive; you can use `--append' (`-r').  The archive must
+already exist in order to use `--append'.  (A related operation is the
+`--update' operation; you can use this to add newer versions of archive
+members to an existing archive.  To learn how to do this with
+`--update', *note update::.)
+
+   If you use `--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.  `tar' _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 `--list' (`-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 `--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
+`--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 _replace_ a file of the same
+name which existed in the directory already, and `tar' will not prompt
+you about this(1).  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 `--occurrence' option.  If you run `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 `archive.tar' contained three copies
+of file `myfile', then the command
+
+     tar --extract --file archive.tar --occurrence=2 myfile
+
+would extract only the second copy.  *Note --occurrence: Option
+Summary, for the description of `--occurrence' option.
+
+   If you want to replace an archive member, use `--delete' to delete
+the member you want to remove from the archive, , and then use
+`--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 *note
+delete:: and *note Media::, for more information.)
+
+* Menu:
+
+* appending files::             Appending Files to an Archive
+* multiple::
+
+   ---------- Footnotes ----------
+
+   (1) Unless you give it `--keep-old-files' option, or the disk copy
+is newer than the the one in the archive and you invoke `tar' with
+`--keep-newer-files' option
+
+
+File: tar.info,  Node: appending files,  Next: multiple,  Up: append
+
+4.2.2.1 Appending Files to an Archive
+.....................................
+
+     _(This message will disappear, once this node revised.)_
+
+The simplest way to add a file to an already existing archive is the
+`--append' (`-r') operation, which writes specified files into the
+archive whether or not they are already among the archived files.
+
+   When you use `--append', you _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 `--verbose' (`-v') option will print out the names of the
+files as they are written into the archive.
+
+   `--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 `tar' archive, or else the results of using this
+operation will be unpredictable.  *Note Media::.
+
+   To demonstrate using `--append' to add a file to an archive, create
+a file called `rock' in the `practice' directory.  Make sure you are in
+the `practice' directory.  Then, run the following `tar' command to add
+`rock' to `collection.tar':
+
+     $ tar --append --file=collection.tar rock
+
+If you now use the `--list' (`-t') operation, you will see that `rock'
+has been added to the archive:
+
+     $ 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
+
+
+File: tar.info,  Node: multiple,  Prev: appending files,  Up: append
+
+4.2.2.2 Multiple Members with the Same Name
+...........................................
+
+You can use `--append' (`-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 `tar' option called `--update'; *Note
+update::, for more information.  We describe this use of `--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 `blues' and then append the changed
+version to `collection.tar'.  As you saw above, the original `blues' is
+in the archive `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 `blues' to the
+archive in this way:
+
+     $ tar --append --verbose --file=collection.tar blues
+     blues
+
+Because you specified the `--verbose' option, `tar' has printed the
+name of the file being appended as it was acted on.  Now list the
+contents of the archive:
+
+     $ 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
+
+The newest version of `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 `blues' will be replaced by the
+newer version.  You can confirm this by extracting the archive and
+running `ls' on the directory.
+
+   If you wish to extract the first occurrence of the file `blues' from
+the archive, use `--occurrence' option, as shown in the following
+example:
+
+     $ tar --extract -vv --occurrence --file=collection.tar blues
+     -rw-r--r-- me user     21 1996-09-23 16:44 blues
+
+   *Note Writing::, for more information on `--extract' and *Note
+-occurrence: Option Summary, for the description of `--occurrence'
+option.
+
+
+File: tar.info,  Node: update,  Next: concatenate,  Prev: append,  Up: Advanced tar
+
+4.2.3 Updating an Archive
+-------------------------
+
+     _(This message will disappear, once this node revised.)_
+
+In the previous section, you learned how to use `--append' to add a
+file to an existing archive.  A related operation is `--update' (`-u').
+The `--update' operation updates a `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 `--append').
+
+   Unfortunately, you cannot use `--update' with magnetic tape drives.
+The operation will fail.
+
+   Both `--update' and `--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
+`--backup' option.  *Note multiple::, for a detailed discussion.
+
+* Menu:
+
+* how to update::
+
+
+File: tar.info,  Node: how to update,  Up: update
+
+4.2.3.1 How to Update an Archive Using `--update'
+.................................................
+
+You must use file name arguments with the `--update' (`-u') operation.
+If you don't specify any files, `tar' won't act on any files and won't
+tell you that it didn't do anything (which may end up confusing you).
+
+   To see the `--update' option at work, create a new file,
+`classical', in your practice directory, and some extra text to the
+file `blues', using any text editor.  Then invoke `tar' with the
+`update' operation and the `--verbose' (`-v') option specified, using
+the names of all the files in the practice directory as file name
+arguments:
+
+     $ tar --update -v -f collection.tar blues folk rock classical
+     blues
+     classical
+     $
+
+Because we have specified verbose mode, `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 `tar --list' and look at
+the archive, you will see `blues' and `classical' at its end.  There
+will be a total of two versions of the member `blues'; the one at the
+end will be newer and larger, since you added text before updating it.
+
+   (The reason `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.  *Note Media::, for
+more information about tapes.
+
+   `--update' (`-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 GNU `tar' options intended
+specifically for backups are more efficient.  If you need to run
+backups, please consult *note Backups::.
+
+
+File: tar.info,  Node: concatenate,  Next: delete,  Prev: update,  Up: Advanced tar
+
+4.2.4 Combining Archives with `--concatenate'
+---------------------------------------------
+
+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
+`--concatenate' (`--catenate', `-A') operation.
+
+   To use `--concatenate', give the first archive with `--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.  (1) The new, concatenated archive will be
+called by the same name as the one given with the `--file' option.  As
+usual, if you omit `--file', `tar' will use the value of the environment
+variable `TAPE', or, if this has not been set, the default archive name.
+
+   To demonstrate how `--concatenate' works, create two small archives
+called `bluesrock.tar' and `folkjazz.tar', using the relevant files
+from `practice':
+
+     $ tar -cvf bluesrock.tar blues rock
+     blues
+     rock
+     $ tar -cvf folkjazz.tar folk jazz
+     folk
+     jazz
+
+If you like, You can run `tar --list' to make sure the archives contain
+what they are supposed to:
+
+     $ 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
+     $ 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
+
+   We can concatenate these two archives with `tar':
+
+     $ cd ..
+     $ tar --concatenate --file=bluesrock.tar jazzfolk.tar
+
+   If you now list the contents of the `bluesrock.tar', you will see
+that now it also contains the archive members of `jazzfolk.tar':
+
+     $ tar --list --file=bluesrock.tar
+     blues
+     rock
+     folk
+     jazz
+
+   When you use `--concatenate', the source and target archives must
+already exist and must have been created using compatible format
+parameters.  Notice, that `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 `--append' (`-r'), this operation cannot be performed on some
+tape drives, due to deficiencies in the formats those tape drives use.
+
+   It may seem more intuitive to you to want or try to use `cat' to
+concatenate two archives instead of using the `--concatenate'
+operation; after all, `cat' is the utility for combining files.
+
+   However, `tar' archives incorporate an end-of-file marker which must
+be removed if the concatenated archives are to be read properly as one
+archive.  `--concatenate' removes the end-of-archive marker from the
+target archive before each new archive is appended.  If you use `cat'
+to combine the archives, the result will not be a valid `tar' format
+archive.  If you need to retrieve files from an archive that was added
+to using the `cat' utility, use the `--ignore-zeros' (`-i') option.
+*Note Ignore Zeros::, for further information on dealing with archives
+improperly combined using the `cat' shell utility.
+
+   ---------- Footnotes ----------
+
+   (1) This can cause multiple members to have the same name, for
+information on how this affects reading the archive, *note multiple::.
+
+
+File: tar.info,  Node: delete,  Next: compare,  Prev: concatenate,  Up: Advanced tar
+
+4.2.5 Removing Archive Members Using `--delete'
+-----------------------------------------------
+
+     _(This message will disappear, once this node revised.)_
+
+You can remove members from an archive by using the `--delete' option.
+Specify the name of the archive with `--file' (`-f') and then specify
+the names of the members to be deleted; if you list no member names,
+nothing will be deleted.  The `--verbose' option will cause `tar' to
+print the names of the members as they are deleted. As with
+`--extract', you must give the exact member names when using `tar
+--delete'.  `--delete' will remove all versions of the named file from
+the archive.  The `--delete' operation can run very slowly.
+
+   Unlike other operations, `--delete' has no short form.
+
+   This operation will rewrite the archive.  You can only use
+`--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.  *Note Media::.
+
+   To delete all versions of the file `blues' from the archive
+`collection.tar' in the `practice' directory, make sure you are in that
+directory, and then,
+
+     $ tar --list --file=collection.tar
+     blues
+     folk
+     jazz
+     rock
+     $ tar --delete --file=collection.tar blues
+     $ tar --list --file=collection.tar
+     folk
+     jazz
+     rock
+     $
+
+   The `--delete' option has been reported to work properly when `tar'
+acts as a filter from `stdin' to `stdout'.
+
+
+File: tar.info,  Node: compare,  Prev: delete,  Up: Advanced tar
+
+4.2.6 Comparing Archive Members with the File System
+----------------------------------------------------
+
+     _(This message will disappear, once this node revised.)_
+
+The `--compare' (`-d'), or `--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 _only_ specify archive member names, not file names.  If you
+do not name any members, then `tar' will compare the entire archive.
+If a file is represented in the archive but does not exist in the file
+system, `tar' reports a difference.
+
+   You have to specify the record size of the archive when modifying an
+archive with a non-default record size.
+
+   `tar' ignores files in the file system that do not have
+corresponding members in the archive.
+
+   The following example compares the archive members `rock', `blues'
+and `funk' in the archive `bluesrock.tar' with files of the same name
+in the file system.  (Note that there is no file, `funk'; `tar' will
+report an error message.)
+
+     $ tar --compare --file=bluesrock.tar rock blues funk
+     rock
+     blues
+     tar: funk not found in archive
+
+   The spirit behind the `--compare' (`--diff', `-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, *Note verify::.
+
+
+File: tar.info,  Node: create options,  Next: extract options,  Prev: Advanced tar,  Up: operations
+
+4.3 Options Used by `--create'
+==============================
+
+The previous chapter described the basics of how to use `--create'
+(`-c') to create an archive from a set of files.  *Note create::.  This
+section described advanced options to be used with `--create'.
+
+* Menu:
+
+* override::                  Overriding File Metadata.
+* Ignore Failed Read::
+
+
+File: tar.info,  Node: override,  Next: Ignore Failed Read,  Up: create options
+
+4.3.1 Overriding File Metadata
+------------------------------
+
+As described above, a `tar' archive keeps, for each member it contains,
+its "metadata", such as modification time, mode and ownership of the
+file.  GNU `tar' 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
+*note PAX keywords::, for additional ways of controlling metadata,
+stored in the archive.
+
+`--mode=PERMISSIONS'
+     When adding files to an archive, `tar' will use PERMISSIONS for
+     the archive members, rather than the permissions from the files.
+     PERMISSIONS can be specified either as an octal number or as
+     symbolic permissions, like with `chmod' (*Note Permissions:
+     (fileutils)File permissions.  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 `a+rw' adds read and write
+     permissions for everybody, while retaining executable bits on
+     directories or on any other file already marked as executable:
+
+          $ tar -c -f archive.tar --mode='a+rw' .
+
+`--mtime=DATE'
+     When adding files to an archive, `tar' will use DATE as the
+     modification time of members when creating archives, instead of
+     their actual modification times.  The argument DATE can be either
+     a textual date representation in almost arbitrary format (*note
+     Date input formats::) or a name of the existing file, starting
+     with `/' or `.'.  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:
+
+          $ tar -c -f archive.tar --mtime='1970-01-01' .
+
+     When used with `--verbose' (*note verbose tutorial::) GNU `tar'
+     will try to convert the specified date back to its textual
+     representation and compare it with the one given with `--mtime'
+     options.  If the two dates differ, `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:
+
+          $ tar -c -f archive.tar -v --mtime=yesterday .
+          tar: Option --mtime: Treating date `yesterday' as 2006-06-20
+          13:06:29.152478
+          ...
+
+`--owner=USER'
+     Specifies that `tar' should use USER as the owner of members when
+     creating archives, instead of the user associated with the source
+     file.  The argument USER can be either an existing user symbolic
+     name, or a decimal numeric user ID.
+
+     There is no value indicating a missing number, and `0' usually
+     means `root'.  Some people like to force `0' as the value to offer
+     in their distributions for the owner of files, because the `root'
+     user is anonymous anyway, so that might as well be the owner of
+     anonymous archives.  For example:
+
+          $ tar -c -f archive.tar --owner=0 .
+          # Or:
+          $ tar -c -f archive.tar --owner=root .
+
+`--group=GROUP'
+     Files added to the `tar' archive will have a group ID of GROUP,
+     rather than the group from the source file.  The argument GROUP
+     can be either an existing group symbolic name, or a decimal
+     numeric group ID.
+
+
+File: tar.info,  Node: Ignore Failed Read,  Prev: override,  Up: create options
+
+4.3.2 Ignore Fail Read
+----------------------
+
+`--ignore-failed-read'
+     Do not exit with nonzero on unreadable files or directories.
+
+
+File: tar.info,  Node: extract options,  Next: backup,  Prev: create options,  Up: operations
+
+4.4 Options Used by `--extract'
+===============================
+
+     _(This message will disappear, once this node revised.)_
+
+The previous chapter showed how to use `--extract' to extract an
+archive into the file system.  Various options cause `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 `--extract' when certain special
+considerations arise.  You may review the information presented in
+*note extract:: for more basic information about the `--extract'
+operation.
+
+* Menu:
+
+* Reading::                     Options to Help Read Archives
+* Writing::                     Changing How `tar' Writes Files
+* Scarce::                      Coping with Scarce Resources
+
+
+File: tar.info,  Node: Reading,  Next: Writing,  Up: extract options
+
+4.4.1 Options to Help Read Archives
+-----------------------------------
+
+     _(This message will disappear, once this node revised.)_
+
+Normally, `tar' will request data in full record increments from an
+archive storage device.  If the device cannot return a full record,
+`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 `--read-full-records' (`-B')
+option in conjunction with the `--extract' or `--list' operations.
+*Note Blocking::.
+
+   The `--read-full-records' (`-B') option is turned on by default when
+`tar' reads an archive from standard input, or from a remote machine.
+This is because on BSD Unix systems, attempting to read a pipe returns
+however much happens to be in the pipe, even if it is less than was
+requested.  If this option were not enabled, `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 `--read-full-records' (`-B') and
+`--blocking-factor=512-SIZE' (`-b 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.  *Note Blocking Factor::.
+
+* Menu:
+
+* read full records::
+* Ignore Zeros::
+
+
+File: tar.info,  Node: read full records,  Next: Ignore Zeros,  Up: Reading
+
+Reading Full Records
+....................
+
+`--read-full-records'
+
+`-B'
+     Use in conjunction with `--extract' (`--get', `-x') to read an
+     archive which contains incomplete records, or one which has a
+     blocking factor less than the one specified.
+
+
+File: tar.info,  Node: Ignore Zeros,  Prev: read full records,  Up: Reading
+
+Ignoring Blocks of Zeros
+........................
+
+Normally, `tar' stops reading when it encounters a block of zeros
+between file entries (which usually indicates the end of the archive).
+`--ignore-zeros' (`-i') allows `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 `--ignore-zeros' (`-i') option is turned off by default because
+many versions of `tar' write garbage after the end-of-archive entry,
+since that part of the media is never supposed to be read.  GNU `tar'
+does not write after the end of an archive, but seeks to maintain
+compatibility among archiving utilities.
+
+`--ignore-zeros'
+`-i'
+     To ignore blocks of zeros (i.e., end-of-archive entries) which may
+     be encountered while reading an archive.  Use in conjunction with
+     `--extract' or `--list'.
+
+
+File: tar.info,  Node: Writing,  Next: Scarce,  Prev: Reading,  Up: extract options
+
+4.4.2 Changing How `tar' Writes Files
+-------------------------------------
+
+     _(This message will disappear, once this node revised.)_
+
+* 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::
+
+
+File: tar.info,  Node: Dealing with Old Files,  Next: Overwrite Old Files,  Up: Writing
+
+Options Controlling the Overwriting of Existing Files
+.....................................................
+
+When extracting files, if `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, `tar' normally overwrites its metadata (ownership,
+permission, etc.).  The `--overwrite-dir' option enables this default
+behavior.  To be more cautious and preserve the metadata of such a
+directory, use the `--no-overwrite-dir' option.
+
+   To be even more cautious and prevent existing files from being
+replaced, use the `--keep-old-files' (`-k') option.  It causes `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.
+
+   To be more aggressive about altering existing files, use the
+`--overwrite' option.  It causes `tar' to overwrite existing files and
+to follow existing symbolic links when extracting.
+
+   Some people argue that GNU `tar' should not hesitate to overwrite
+files with other files when extracting.  When extracting a `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 `usr/local' is a link to `usr/local2'.  Since then, maybe the
+site removed the link and renamed the whole hierarchy from
+`/usr/local2' to `/usr/local'.  Such things happen all the time.  I
+guess it would not be welcome at all that GNU `tar' removes the whole
+hierarchy just to make room for the link to be reinstated (unless it
+_also_ simultaneously restores the full `/usr/local2', of course!)  GNU
+`tar' is indeed able to remove a whole hierarchy to reestablish a
+symbolic link, for example, but _only if_ `--recursive-unlink' is
+specified to allow this behavior.  In any case, single files are
+silently removed.
+
+   Finally, the `--unlink-first' (`-U') option can improve performance
+in some cases by causing `tar' to remove files unconditionally before
+extracting them.
+
+
+File: tar.info,  Node: Overwrite Old Files,  Next: Keep Old Files,  Prev: Dealing with Old Files,  Up: Writing
+
+Overwrite Old Files
+...................
+
+`--overwrite'
+     Overwrite existing files and directory metadata when extracting
+     files from an archive.
+
+     This causes `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 `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 `--overwrite' option, particularly when
+     combined with the `--absolute-names' (`-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.
+
+`--overwrite-dir'
+     Overwrite the metadata of directories when extracting files from an
+     archive, but remove other files before extracting.
+
+
+File: tar.info,  Node: Keep Old Files,  Next: Keep Newer Files,  Prev: Overwrite Old Files,  Up: Writing
+
+Keep Old Files
+..............
+
+`--keep-old-files'
+`-k'
+     Do not replace existing files from archive.  The
+     `--keep-old-files' (`-k') option prevents `tar' from replacing
+     existing files with files with the same name from the archive. The
+     `--keep-old-files' option is meaningless with `--list' (`-t').
+     Prevents `tar' from replacing files in the file system during
+     extraction.
+
+
+File: tar.info,  Node: Keep Newer Files,  Next: Unlink First,  Prev: Keep Old Files,  Up: Writing
+
+Keep Newer Files
+................
+
+`--keep-newer-files'
+     Do not replace existing files that are newer than their archive
+     copies.  This option is meaningless with `--list' (`-t').
+
+
+File: tar.info,  Node: Unlink First,  Next: Recursive Unlink,  Prev: Keep Newer Files,  Up: Writing
+
+Unlink First
+............
+
+`--unlink-first'
+`-U'
+     Remove files before extracting over them.  This can make `tar' run
+     a bit faster if you know in advance that the extracted files all
+     need to be removed.  Normally this option slows `tar' down
+     slightly, so it is disabled by default.
+
+
+File: tar.info,  Node: Recursive Unlink,  Next: Data Modification Times,  Prev: Unlink First,  Up: Writing
+
+Recursive Unlink
+................
+
+`--recursive-unlink'
+     When this option is specified, try removing files and directory
+     hierarchies before extracting over them.  _This is a dangerous
+     option!_
+
+   If you specify the `--recursive-unlink' option, `tar' removes
+_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.
+
+
+File: tar.info,  Node: Data Modification Times,  Next: Setting Access Permissions,  Prev: Recursive Unlink,  Up: Writing
+
+Setting Data Modification Times
+...............................
+
+Normally, `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 `umask'
+setting.
+
+   To set the data modification times of extracted files to the time
+when the files were extracted, use the `--touch' (`-m') option in
+conjunction with `--extract' (`--get', `-x').
+
+`--touch'
+`-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 `--extract' (`--get', `-x').
+
+
+File: tar.info,  Node: Setting Access Permissions,  Next: Directory Modification Times and Permissions,  Prev: Data Modification Times,  Up: Writing
+
+Setting Access Permissions
+..........................
+
+To set the modes (access permissions) of extracted files to those
+recorded for those files in the archive, use `--same-permissions' in
+conjunction with the `--extract' (`--get', `-x') operation.
+
+`--preserve-permissions'
+`--same-permissions'
+`-p'
+     Set modes of extracted archive members to those recorded in the
+     archive, instead of current umask settings.  Use in conjunction
+     with `--extract' (`--get', `-x').
+
+
+File: tar.info,  Node: Directory Modification Times and Permissions,  Next: Writing to Standard Output,  Prev: Setting Access Permissions,  Up: Writing
+
+Directory Modification Times and Permissions
+............................................
+
+After successfully extracting a file member, GNU `tar' normally
+restores its permissions and modification times, as described in the
+previous sections.  This cannot be done for directories, because after
+extracting a directory `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.  GNU `tar' 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, GNU `tar' 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 `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 (*note 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, GNU `tar' 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 GNU `tar'
+automatically detects archives in incremental format.
+
+   There may be cases, when such processing is required for normal
+archives too.  Consider the following example:
+
+     $ tar --no-recursion -cvf archive \
+         foo foo/file1 bar bar/file foo/file2
+     foo/
+     foo/file1
+     bar/
+     bar/file
+     foo/file2
+
+   During the normal operation, after encountering `bar' GNU `tar' will
+assume that all files from the directory `foo' were already extracted
+and will therefore restore its timestamp and permission bits.  However,
+after extracting `foo/file2' the directory timestamp will be offset
+again.
+
+   To correctly restore directory meta-information in such cases, use
+`delay-directory-restore' command line option:
+
+`--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.
+
+`--no-delay-directory-restore'
+     Cancel the effect of the previous `--delay-directory-restore'.
+     Use this option if you have used `--delay-directory-restore' in
+     `TAR_OPTIONS' variable (*note TAR_OPTIONS::) and wish to
+     temporarily disable it.
+
+
+File: tar.info,  Node: Writing to Standard Output,  Next: Writing to an External Program,  Prev: Directory Modification Times and Permissions,  Up: Writing
+
+Writing to Standard Output
+..........................
+
+To write the extracted files to the standard output, instead of
+creating the files on the file system, use `--to-stdout' (`-O') in
+conjunction with `--extract' (`--get', `-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.
+
+`--to-stdout'
+`-O'
+     Writes files to the standard output.  Use only in conjunction with
+     `--extract' (`--get', `-x').  When this option is used, instead of
+     creating the files specified, `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 `--list' (`-t').
+
+   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:
+
+     tar -xOzf foo.tgz bigfile | process
+
+   or even like this if you want to process the concatenation of the
+files:
+
+     tar -xOzf foo.tgz bigfile1 bigfile2 | process
+
+   However, `--to-command' may be more convenient for use with multiple
+files. See the next section.
+
+
+File: tar.info,  Node: Writing to an External Program,  Next: remove files,  Prev: Writing to Standard Output,  Up: Writing
+
+Writing to an External Program
+..............................
+
+You can instruct `tar' to send the contents of each extracted file to
+the standard input of an external program:
+
+`--to-command=COMMAND'
+     Extract files and pipe their contents to the standard input of
+     COMMAND. When this option is used, instead of creating the files
+     specified, `tar' invokes COMMAND and pipes the contents of the
+     files to its standard output. COMMAND may contain command line
+     arguments. The program is executed via `sh -c'. Notice, that
+     COMMAND is executed once for each regular file extracted.
+     Non-regular files (directories, etc.) are ignored when this option
+     is used.
+
+   The command can obtain the information about the file it processes
+from the following environment variables:
+
+TAR_FILETYPE
+     Type of the file. It is a single letter with the following meaning:
+
+     f       Regular file
+     d       Directory
+     l       Symbolic link
+     h       Hard link
+     b       Block device
+     c       Character device
+
+     Currently only regular files are supported.
+
+TAR_MODE
+     File mode, an octal number.
+
+TAR_FILENAME
+     The name of the file.
+
+TAR_REALNAME
+     Name of the file as stored in the archive.
+
+TAR_UNAME
+     Name of the file owner.
+
+TAR_GNAME
+     Name of the file owner group.
+
+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.
+
+TAR_MTIME
+     Time of last modification.
+
+TAR_CTIME
+     Time of last status change.
+
+TAR_SIZE
+     Size of the file.
+
+TAR_UID
+     UID of the file owner.
+
+TAR_GID
+     GID of the file owner.
+
+   In addition to these variables, `TAR_VERSION' contains the GNU `tar'
+version number.
+
+   If COMMAND exits with a non-0 status, `tar' will print an error
+message similar to the following:
+
+     tar: 2345: Child returned status 1
+
+   Here, `2345' is the PID of the finished process.
+
+   If this behavior is not wanted, use `--ignore-command-error':
+
+`--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.
+
+`--no-ignore-command-error'
+     Cancel the effect of any previous `--ignore-command-error' option.
+     This option is useful if you have set `--ignore-command-error' in
+     `TAR_OPTIONS' (*note TAR_OPTIONS::) and wish to temporarily cancel
+     it.
+
+
+File: tar.info,  Node: remove files,  Prev: Writing to an External Program,  Up: Writing
+
+Removing Files
+..............
+
+`--remove-files'
+     Remove files after adding them to the archive.
+
+
+File: tar.info,  Node: Scarce,  Prev: Writing,  Up: extract options
+
+4.4.3 Coping with Scarce Resources
+----------------------------------
+
+     _(This message will disappear, once this node revised.)_
+
+* Menu:
+
+* Starting File::
+* Same Order::
+
+
+File: tar.info,  Node: Starting File,  Next: Same Order,  Up: Scarce
+
+Starting File
+.............
+
+`--starting-file=NAME'
+`-K NAME'
+     Starts an operation in the middle of an archive.  Use in
+     conjunction with `--extract' (`--get', `-x') or `--list' (`-t').
+
+   If a previous attempt to extract files failed due to lack of disk
+space, you can use `--starting-file=NAME' (`-K NAME') to start
+extracting only after member 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 `tar',
+remove unnecessary files from the file system, and then restart the
+same `tar' operation.  In this case, `--starting-file' is not necessary.
+*Note Incremental Dumps::, *Note interactive::, and *note exclude::.)
+
+
+File: tar.info,  Node: Same Order,  Prev: Starting File,  Up: Scarce
+
+Same Order
+..........
+
+`--same-order'
+`--preserve-order'
+`-s'
+     To process large lists of file names on machines with small
+     amounts of memory.  Use in conjunction with `--compare' (`--diff',
+     `-d'), `--list' (`-t') or `--extract' (`--get', `-x').
+
+   The `--same-order' (`--preserve-order', `-s') option tells `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 `tar -t' on the archive and
+editing its output.
+
+   This option is probably never needed on modern computer systems.
+
+
+File: tar.info,  Node: backup,  Next: Applications,  Prev: extract options,  Up: operations
+
+4.5 Backup options
+==================
+
+GNU `tar' 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 GNU programs (`cp',
+`install', `ln', and `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.
+
+`--backup[=METHOD]'
+     Back up files that are about to be overwritten or removed.
+     Without this option, the original versions are destroyed.
+
+     Use METHOD to determine the type of backups made.  If METHOD is
+     not specified, use the value of the `VERSION_CONTROL' environment
+     variable.  And if `VERSION_CONTROL' is not set, use the `existing'
+     method.
+
+     This option corresponds to the Emacs variable `version-control';
+     the same values for METHOD are accepted as in Emacs.  This option
+     also allows more descriptive names.  The valid METHODs are:
+
+    `t'
+    `numbered'
+          Always make numbered backups.
+
+    `nil'
+    `existing'
+          Make numbered backups of files that already have them, simple
+          backups of the others.
+
+    `never'
+    `simple'
+          Always make simple backups.
+
+
+`--suffix=SUFFIX'
+     Append SUFFIX to each backup file made with `--backup'.  If this
+     option is not specified, the value of the `SIMPLE_BACKUP_SUFFIX'
+     environment variable is used.  And if `SIMPLE_BACKUP_SUFFIX' is not
+     set, the default is `~', just as in Emacs.
+
+
+
+File: tar.info,  Node: Applications,  Next: looking ahead,  Prev: backup,  Up: operations
+
+4.6 Notable `tar' Usages
+========================
+
+     _(This message will disappear, once this node revised.)_
+
+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 `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 `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 "pipe", which is one a Unix redirection mechanism:
+
+     $ (cd sourcedir; tar -cf - .) | (cd targetdir; tar -xf -)
+
+You can avoid subshells by using `-C' option:
+
+     $ tar -C sourcedir -cf - . | tar -C targetdir -xf -
+
+The command also works using short option forms:
+
+     $ (cd sourcedir; tar --create --file=- . ) \
+            | (cd targetdir; tar --extract --file=-)
+     # Or:
+     $ tar --directory sourcedir --create --file=- . ) \
+            | tar --directory targetdir --extract --file=-
+
+This is one of the easiest methods to transfer a `tar' archive.
+
+
+File: tar.info,  Node: looking ahead,  Prev: Applications,  Up: operations
+
+4.7 Looking Ahead: The Rest of this Manual
+==========================================
+
+You have now seen how to use all eight of the operations available to
+`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
+`tar' (this can help you save time if you expect to archive the same
+list of files a number of times), and so forth.
+
+   If there are too many files to conveniently list on the command line,
+you can list the names in a file, and `tar' will read that file.  *Note
+files::.
+
+   There are various ways of causing `tar' to skip over some files, and
+not archive them.  *Note Choosing::.
+
+
+File: tar.info,  Node: Backups,  Next: Choosing,  Prev: operations,  Up: Top
+
+5 Performing Backups and Restoring Files
+****************************************
+
+     _(This message will disappear, once this node revised.)_
+
+GNU `tar' 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 `Amanda' (The Advanced Maryland
+Automatic Network Disk Archiver), a backup system developed by James da
+Silva `jds@cs.umd.edu' and available on many Unix systems.  This is
+free software, and it is available at these places:
+
+     http://www.cs.umd.edu/projects/amanda/amanda.html
+     ftp://ftp.cs.umd.edu/pub/amanda
+
+   This chapter documents both the provided shell scripts and `tar'
+options which are more specific to usage as a backup tool.
+
+   To "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 "backups" are also called
+"dumps".
+
+* Menu:
+
+* Full Dumps::                  Using `tar' to Perform Full Dumps
+* Incremental Dumps::           Using `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
+
+
+File: tar.info,  Node: Full Dumps,  Next: Incremental Dumps,  Up: Backups
+
+5.1 Using `tar' to Perform Full Dumps
+=====================================
+
+     _(This message will disappear, once this node revised.)_
+
+Full dumps should only be made when no other people or programs are
+modifying files in the file system.  If files are modified while `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 `--label=ARCHIVE-LABEL' (`-V
+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 `--multi-volume' (`-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 `--one-file-system' option to prevent `tar' from crossing file
+system boundaries when storing (sub)directories.
+
+   The `--incremental' (`-G') (*note 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 `tar' program (and your
+tapes), it is a good idea to use the `--verify' (`-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.
+
+
+File: tar.info,  Node: Incremental Dumps,  Next: Backup Levels,  Prev: Full Dumps,  Up: Backups
+
+5.2 Using `tar' to Perform Incremental Dumps
+============================================
+
+"Incremental backup" is a special form of GNU `tar' archive that stores
+additional metadata so that exact state of the file system can be
+restored when extracting the archive.
+
+   GNU `tar' currently offers two options for handling incremental
+backups: `--listed-incremental=SNAPSHOT-FILE' (`-g SNAPSHOT-FILE') and
+`--incremental' (`-G').
+
+   The option `--listed-incremental' instructs tar to operate on an
+incremental archive with additional metadata stored in a standalone
+file, called a "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:
+
+`--listed-incremental=FILE'
+`-g FILE'
+     Handle incremental backups with snapshot data in FILE.
+
+   To create an incremental backup, you would use
+`--listed-incremental' together with `--create' (*note create::).  For
+example:
+
+     $ tar --create \
+                --file=archive.1.tar \
+                --listed-incremental=/var/log/usr.snar \
+                /usr
+
+   This will create in `archive.1.tar' an incremental backup of the
+`/usr' file system, storing additional metadata in the file
+`/var/log/usr.snar'.  If this file does not exist, it will be created.
+The created archive will then be a "level 0 backup"; please see the
+next section for more on backup levels.
+
+   Otherwise, if the 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 `/usr/doc/old' and create directory
+`/usr/local/db' with the following contents:
+
+     $ ls /usr/local/db
+     /usr/local/db/data
+     /usr/local/db/index
+
+   Some time later you create another incremental backup.  You will
+then see:
+
+     $ 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
+
+The created archive `archive.2.tar' will contain only these three
+members.  This archive is called a "level 1 backup".  Notice that
+`/var/log/usr.snar' will be updated with the new data, so if you plan
+to create more `level 1' backups, it is necessary to create a working
+copy of the snapshot file before running `tar'.  The above example will
+then be modified as follows:
+
+     $ cp /var/log/usr.snar /var/log/usr.snar-1
+     $ tar --create \
+                --file=archive.2.tar \
+                --listed-incremental=/var/log/usr.snar-1 \
+                /usr
+
+   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 `--atime-preserve=replace' option), or if you set the clock
+backwards.
+
+   Metadata stored in snapshot files include device numbers, which,
+obviously is supposed to be a non-volatile value.  However, it turns
+out that NFS devices have undependable values when an automounter gets
+in the picture.  This can lead to a great deal of spurious redumping in
+incremental dumps, so it is somewhat useless to compare two NFS devices
+numbers over time.  The solution implemented currently is to considers
+all NFS devices as being equal when it comes to comparing directories;
+this is fairly gross, but there does not seem to be a better way to go.
+
+   Note that incremental archives use `tar' extensions and may not be
+readable by non-GNU versions of the `tar' program.
+
+   To extract from the incremental dumps, use `--listed-incremental'
+together with `--extract' option (*note extracting files::).  In this
+case, `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 `--listed-incremental',
+the usual practice is to use `--listed-incremental=/dev/null'.
+Alternatively, you can use `--incremental', which needs no arguments.
+In general, `--incremental' (`-G') can be used as a shortcut for
+`--listed-incremental' when listing or extracting incremental backups
+(for more information, regarding this option, *note incremental-op::).
+
+   When extracting from the incremental backup GNU `tar' attempts to
+restore the exact state the file system had when the archive was
+created.  In particular, it will _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 `/usr' file
+system, one would do(1):
+
+     $ tar --extract \
+                --listed-incremental=/dev/null \
+                --file archive.1.tar
+     $ tar --extract \
+                --listed-incremental=/dev/null \
+                --file archive.2.tar
+
+   To list the contents of an incremental archive, use `--list' (*note
+list::), as usual.  To obtain more information about the archive, use
+`--listed-incremental' or `--incremental' combined with two `--verbose'
+options(2):
+
+     tar --list --incremental --verbose --verbose archive.tar
+
+   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
+
+     X FILE
+
+where X is a letter describing the status of the file: `Y' if the file
+is present in the archive, `N' if the file is not included in the
+archive, or a `D' if the file is a directory (and is included in the
+archive).  *Note 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.
+
+   The option `--incremental' (`-G') gives the same behavior as
+`--listed-incremental' when used with `--list' and `--extract' options.
+When used with `--create' option, it creates an incremental archive
+without creating snapshot file.  Thus, it is impossible to create
+several levels of incremental backups with `--incremental' option.
+
+   ---------- Footnotes ----------
+
+   (1) Notice, that since both archives were created without `-P'
+option (*note absolute::), these commands should be run from the root
+file system.
+
+   (2) Two `--verbose' options were selected to avoid breaking usual
+verbose listing output (`--list --verbose') when using in scripts.
+
+   Versions of GNU `tar' up to 1.15.1 used to dump verbatim binary
+contents of the DUMPDIR header (with terminating nulls) when
+`--incremental' or `--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
+
+
+File: tar.info,  Node: Backup Levels,  Next: Backup Parameters,  Prev: Incremental Dumps,  Up: Backups
+
+5.3 Levels of Backups
+=====================
+
+An archive containing all the files in the file system is called a
+"full backup" or "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 "incremental dumps".  A "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).
+
+   GNU `tar' 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 `tar' commands
+by hand.
+
+   Before you use these scripts, you need to edit the file
+`backup-specs', which specifies parameters used by the backup scripts
+and by the restore script.  This file is usually located in
+`/etc/backup' directory.  *Note 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 `backup'.  The name of the restore
+script is `restore'.  The following sections describe their use in
+detail.
+
+   _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.  *Note Incremental Dumps::, before
+making such an attempt.
+
+
+File: tar.info,  Node: Backup Parameters,  Next: Scripted Backups,  Prev: Backup Levels,  Up: Backups
+
+5.4 Setting Parameters for Backups and Restoration
+==================================================
+
+The file `backup-specs' specifies backup parameters for the backup and
+restoration scripts provided with `tar'.  You must edit `backup-specs'
+to fit your system configuration and schedule before using these
+scripts.
+
+   Syntactically, `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 `RESTORE_BEGIN' below).  For more information about
+shell script syntax, please refer to the definition of the Shell
+Command Language
+(http://www.opengroup.org/onlinepubs/009695399/utilities/xcu_chap02.html#ta
+g_02).  See also *note Bash Features: (bashref)Top.
+
+   The shell variables controlling behavior of `backup' and `restore'
+are described in the following subsections.
+
+* Menu:
+
+* General-Purpose Variables::
+* Magnetic Tape Control::
+* User Hooks::
+* backup-specs example::        An Example Text of `Backup-specs'
+
+
+File: tar.info,  Node: General-Purpose Variables,  Next: Magnetic Tape Control,  Up: Backup Parameters
+
+5.4.1 General-Purpose Variables
+-------------------------------
+
+ -- Backup variable: ADMINISTRATOR
+     The user name of the backup administrator.  `Backup' scripts sends
+     a backup report to this address.
+
+ -- 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 HOURS:MINUTES, or the
+     string `now'.
+
+     This variable is used by `backup'.  Its value may be overridden
+     using `--time' option (*note Scripted Backups::).
+
+ -- Backup variable: TAPE_FILE
+     The device `tar' writes the archive to.  If TAPE_FILE is a remote
+     archive (*note remote-dev::), backup script will suppose that your
+     `mt' is able to access remote devices.  If RSH (*note RSH::) is
+     set, `--rsh-command' option will be added to invocations of `mt'.
+
+ -- Backup variable: BLOCKING
+     The blocking factor `tar' will use when writing the dump archive.
+     *Note Blocking Factor::.
+
+ -- Backup variable: BACKUP_DIRS
+     A list of file systems to be dumped (for `backup'), or restored
+     (for `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 `tar' on, and should
+     normally be the host that actually contains the file system.
+     However, the host machine must have GNU `tar' installed, and must
+     be able to access the directory containing the backup scripts and
+     their support files using the same file name that is used on the
+     machine where the scripts are run (i.e., what `pwd' will print
+     when in that directory on that machine).  If the host that contains
+     the file system does not have this capability, you can specify
+     another host as long as it can access the file system through NFS.
+
+     If the list of file systems is very long you may wish to put it in
+     a separate file.  This file is usually named `/etc/backup/dirs',
+     but this name may be overridden in `backup-specs' using `DIRLIST'
+     variable.
+
+ -- Backup variable: DIRLIST
+     The name of the file that contains a list of file systems to backup
+     or restore.  By default it is `/etc/backup/dirs'.
+
+ -- Backup variable: BACKUP_FILES
+     A list of individual files to be dumped (for `backup'), or restored
+     (for `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
+     `/etc/backup/files', but this name may be overridden in
+     `backup-specs' using `FILELIST' variable.
+
+ -- Backup variable: FILELIST
+     The name of the file that contains a list of individual files to
+     backup or restore.  By default it is `/etc/backup/files'.
+
+ -- Backup variable: MT
+     Full file name of `mt' binary.
+
+ -- Backup variable: RSH
+     Full file name of `rsh' binary or its equivalent.  You may wish to
+     set it to `ssh', to improve security.  In this case you will have
+     to use public key authentication.
+
+ -- Backup variable: RSH_COMMAND
+     Full file name of `rsh' binary on remote machines.  This will be
+     passed via `--rsh-command' option to the remote invocation of GNU
+     `tar'.
+
+ -- 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.
+
+ -- Backup variable: XLIST
+     Name of "exclude file list".  An "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.,
+     `/etc/shadow' from backups).
+
+     This variable affects only `backup'.
+
+ -- Backup variable: SLEEP_TIME
+     Time to sleep between dumps of any two successive file systems
+
+     This variable affects only `backup'.
+
+ -- 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, GNU `tar' will display
+     its built-in prompt, and will expect confirmation from the
+     console.  For the description of the default prompt, see *note
+     change volume prompt::.
+
+
+ -- Backup variable: SLEEP_MESSAGE
+     Message to display on the terminal while waiting for dump time.
+     Usually this will just be some literal text.
+
+ -- Backup variable: TAR
+     Full file name of the GNU `tar' executable.  If this is not set,
+     backup scripts will search `tar' in the current shell path.
+
+
+File: tar.info,  Node: Magnetic Tape Control,  Next: User Hooks,  Prev: General-Purpose Variables,  Up: Backup Parameters
+
+5.4.2 Magnetic Tape Control
+---------------------------
+
+Backup scripts access tape device using special "hook functions".
+These functions take a single argument - the name of the tape device.
+Their names are kept in the following variables:
+
+ -- Backup variable: MT_BEGIN
+     The name of "begin" function.  This function is called before
+     accessing the drive.  By default it retensions the tape:
+
+          MT_BEGIN=mt_begin
+
+          mt_begin() {
+              mt -f "$1" retension
+          }
+
+ -- Backup variable: MT_REWIND
+     The name of "rewind" function.  The default definition is as
+     follows:
+
+          MT_REWIND=mt_rewind
+
+          mt_rewind() {
+              mt -f "$1" rewind
+          }
+
+
+ -- Backup variable: MT_OFFLINE
+     The name of the function switching the tape off line.  By default
+     it is defined as follows:
+
+          MT_OFFLINE=mt_offline
+
+          mt_offline() {
+              mt -f "$1" offl
+          }
+
+ -- Backup variable: MT_STATUS
+     The name of the function used to obtain the status of the archive
+     device, including error count.  Default definition:
+
+          MT_STATUS=mt_status
+
+          mt_status() {
+              mt -f "$1" status
+          }
+
+
+File: tar.info,  Node: User Hooks,  Next: backup-specs example,  Prev: Magnetic Tape Control,  Up: Backup Parameters
+
+5.4.3 User Hooks
+----------------
+
+"User hooks" are shell functions executed before and after each `tar'
+invocation.  Thus, there are "backup hooks", which are executed before
+and after dumping each file system, and "restore hooks", executed
+before and after restoring a file system.  Each user hook is a shell
+function taking four arguments:
+
+ -- User Hook Function: hook LEVEL HOST FS FSNAME
+     Its arguments are:
+
+    LEVEL
+          Current backup or restore level.
+
+    HOST
+          Name or IP address of the host machine being dumped or
+          restored.
+
+    FS
+          Full file name of the file system being dumped or restored.
+
+    FSNAME
+          File system name with directory separators replaced with
+          colons.  This is useful, e.g., for creating unique files.
+
+   Following variables keep the names of user hook functions
+
+ -- Backup variable: DUMP_BEGIN
+     Dump begin function.  It is executed before dumping the file
+     system.
+
+ -- Backup variable: DUMP_END
+     Executed after dumping the file system.
+
+ -- Backup variable: RESTORE_BEGIN
+     Executed before restoring the file system.
+
+ -- Backup variable: RESTORE_END
+     Executed after restoring the file system.
+
+
+File: tar.info,  Node: backup-specs example,  Prev: User Hooks,  Up: Backup Parameters
+
+5.4.4 An Example Text of `Backup-specs'
+---------------------------------------
+
+The following is an example of `backup-specs':
+
+     # site-specific parameters for file system backup.
+
+     ADMINISTRATOR=friedman
+     BACKUP_HOUR=1
+     TAPE_FILE=/dev/nrsmt0
+
+     # Use `ssh' instead of the less secure `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]"
+
+
+File: tar.info,  Node: Scripted Backups,  Next: Scripted Restoration,  Prev: Backup Parameters,  Up: Backups
+
+5.5 Using the Backup Scripts
+============================
+
+The syntax for running a backup script is:
+
+     backup --level=LEVEL --time=TIME
+
+   The `level' option requests the dump level.  Thus, to produce a full
+dump, specify `--level=0' (this is the default, so `--level' may be
+omitted if its value is `0').  (1)
+
+   The `--time' option determines when should the backup be run.  TIME
+may take three forms:
+
+HH:MM
+     The dump must be run at HH hours MM minutes.
+
+HH
+     The dump must be run at HH hours
+
+now
+     The dump must be run immediately.
+
+   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
+`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 (*note Scripted Restoration::).
+
+   The backup scripts write two files on the file system.  The first is
+a record file in `/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.  *Note 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
+`log-MM-DD-YYYY-level-N', where MM-DD-YYYY represents current date, and
+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 `backup' script:
+
+`-l LEVEL'
+`--level=LEVEL'
+     Do backup level LEVEL (default 0).
+
+`-f'
+`--force'
+     Force backup even if today's log file already exists.
+
+`-v[LEVEL]'
+`--verbose[=LEVEL]'
+     Set verbosity level.  The higher the level is, the more debugging
+     information will be output during execution.  Default LEVEL is
+     100, which means the highest debugging level.
+
+`-t START-TIME'
+`--time=START-TIME'
+     Wait till TIME, then do backup.
+
+`-h'
+`--help'
+     Display short help message and exit.
+
+`-V'
+`--version'
+     Display information about the program's name, version, origin and
+     legal status, all on standard output, and then exit successfully.
+
+   ---------- Footnotes ----------
+
+   (1) For backward compatibility, the `backup' will also try to deduce
+the requested dump level from the name of the script itself.  If the
+name consists of a string `level-' followed by a single decimal digit,
+that digit is taken as the dump level number.  Thus, you may create a
+link from `backup' to `level-1' and then run `level-1' whenever you
+need to create a level one dump.
+
+
+File: tar.info,  Node: Scripted Restoration,  Prev: Scripted Backups,  Up: Backups
+
+5.6 Using the Restore Script
+============================
+
+To restore files that were archived using a scripted backup, use the
+`restore' script.  Its usage is quite straightforward.  In the simplest
+form, invoke `restore --all', it will then restore all the file systems
+and files specified in `backup-specs' (*note BACKUP_DIRS:
+General-Purpose Variables.).
+
+   You may select the file systems (and/or files) to restore by giving
+`restore' list of "patterns" in its command line.  For example, running
+
+     restore 'albert:*'
+
+will restore all file systems on the machine `albert'.  A more
+complicated example:
+
+     restore 'albert:*' '*:/var'
+
+This command will restore all file systems on the machine `albert' as
+well as `/var' file system on all machines.
+
+   By default `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 `--level'
+option, as shown in the example below:
+
+     restore --level=1
+
+   The full list of options accepted by `restore' follows:
+
+`-a'
+`--all'
+     Restore all file systems and files specified in `backup-specs'
+
+`-l LEVEL'
+`--level=LEVEL'
+     Start restoring from the given backup level, instead of the
+     default 0.
+
+`-v[LEVEL]'
+`--verbose[=LEVEL]'
+     Set verbosity level.  The higher the level is, the more debugging
+     information will be output during execution.  Default LEVEL is
+     100, which means the highest debugging level.
+
+`-h'
+`--help'
+     Display short help message and exit.
+
+`-V'
+`--version'
+     Display information about the program's name, version, origin and
+     legal status, all on standard output, and then exit successfully.
+
+   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.  *Note Tape Positioning::, for a discussion of tape positioning.
+
+     *Warning:* The script will delete files from the active file
+     system if they were not in the file system when the archive was
+     made.
+
+   *Note Incremental Dumps::, for an explanation of how the script makes
+that determination.
+
+
+File: tar.info,  Node: Choosing,  Next: Date input formats,  Prev: Backups,  Up: Top
+
+6 Choosing Files and Names for `tar'
+************************************
+
+     _(This message will disappear, once this node revised.)_
+
+Certain options to `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
+
+
+File: tar.info,  Node: file,  Next: Selecting Archive Members,  Up: Choosing
+
+6.1 Choosing and Naming Archive Files
+=====================================
+
+     _(This message will disappear, once this node revised.)_
+
+By default, `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 `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
+`tar' where to find (or create) the archive.  The `--file=ARCHIVE-NAME'
+(`-f ARCHIVE-NAME') option allows you to either specify or name a file
+to use as the archive instead of the default archive file location.
+
+`--file=ARCHIVE-NAME'
+`-f ARCHIVE-NAME'
+     Name the archive to create or operate on.  Use in conjunction with
+     any operation.
+
+   For example, in this `tar' command,
+
+     $ tar -cvf collection.tar blues folk jazz
+
+`collection.tar' is the name of the archive.  It must directly follow
+the `-f' option, since whatever directly follows `-f' _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 `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.
+
+   If you do not name the archive, `tar' uses the value of the
+environment variable `TAPE' as the file name for the archive.  If that
+is not available, `tar' uses a default, compiled-in archive name,
+usually that for tape unit zero (i.e., `/dev/tu00').
+
+   If you use `-' as an ARCHIVE-NAME, `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 `-' as an
+ARCHIVE-NAME when modifying an archive, `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 `sourcedir' to `targetdir'.
+
+     $ (cd sourcedir; tar -cf - .) | (cd targetdir; tar -xpf -)
+
+   The `-C' option allows to avoid using subshells:
+
+     $ tar -C sourcedir -cf - . | tar -C targetdir -xpf -
+
+   In both examples above, the leftmost `tar' invocation archives the
+contents of `sourcedir' to the standard output, while the rightmost one
+reads this archive from its standard input and extracts it.  The `-p'
+option tells it to restore permissions of the extracted files.
+
+   To specify an archive file on a device attached to a remote machine,
+use the following:
+
+     --file=HOSTNAME:/DEV/FILE-NAME
+
+`tar' will complete the remote connection, if possible, and prompt you
+for a username and password.  If you use
+`--file=@HOSTNAME:/DEV/FILE-NAME', `tar' will complete the remote
+connection, if possible, using your username as the username on the
+remote machine.
+
+   If the archive file name includes a colon (`:'), then it is assumed
+to be a file on another machine.  If the archive file is
+`USER@HOST:FILE', then FILE is used on the host HOST.  The remote host
+is accessed using the `rsh' program, with a username of USER.  If the
+username is omitted (along with the `@' sign), then your user name will
+be used.  (This is the normal `rsh' behavior.)  It is necessary for the
+remote machine, in addition to permitting your `rsh' access, to have
+the `rmt' program installed (This command is included in the GNU `tar'
+distribution and by default is installed under `PREFIX/libexec/rmt',
+were 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 `--force-local' option.
+
+   When the archive is being created to `/dev/null', GNU `tar' tries to
+minimize input and output operations.  The Amanda backup system, when
+used with GNU `tar', has an initial sizing pass which uses this feature.
+
+
+File: tar.info,  Node: Selecting Archive Members,  Next: files,  Prev: file,  Up: Choosing
+
+6.2 Selecting Archive Members
+=============================
+
+"File Name arguments" specify which files in the file system `tar'
+operates on, when creating or adding to an archive, or which archive
+members `tar' operates on, when reading or deleting from an archive.
+*Note Operations::.
+
+   To specify file names, you can include them as the last arguments on
+the command line, as follows:
+     tar OPERATION [OPTION1 OPTION2 ...] [FILE NAME-1 FILE NAME-2 ...]
+
+   If a file name begins with dash (`-'), precede it with `--add-file'
+option to prevent it from being treated as an option.
+
+   By default GNU `tar' attempts to "unquote" each file or member name,
+replacing "escape sequences" according to the following table:
+
+Escape         Replaced with
+----------------------------------------------------------- 
+\a             Audible bell (ASCII 7)
+\b             Backspace (ASCII 8)
+\f             Form feed (ASCII 12)
+\n             New line (ASCII 10)
+\r             Carriage return (ASCII 13)
+\t             Horizontal tabulation (ASCII 9)
+\v             Vertical tabulation (ASCII 11)
+\?             ASCII 127
+\N             ASCII N (N should be an octal number
+                         of up to 3 digits)
+
+   A backslash followed by any other symbol is retained.
+
+   This default behavior is controlled by the following command line
+option:
+
+`--unquote'
+     Enable unquoting input file or member names (default).
+
+`--no-unquote'
+     Disable unquoting input file or member names.
+
+   If you specify a directory name as a file name argument, all the
+files in that directory are operated on by `tar'.
+
+   If you do not specify files, `tar' behavior differs depending on the
+operation mode as described below:
+
+   When `tar' is invoked with `--create' (`-c'), `tar' will stop
+immediately, reporting the following:
+
+     $ tar cf a.tar
+     tar: Cowardly refusing to create an empty archive
+     Try `tar --help' or `tar --usage' for more information.
+
+   If you specify either `--list' (`-t') or `--extract' (`--get',
+`-x'), `tar' operates on all the archive members in the archive.
+
+   If run with `--diff' option, tar will compare the archive with the
+contents of the current working directory.
+
+   If you specify any other operation, `tar' does nothing.
+
+   By default, `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 `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.
+
+
+File: tar.info,  Node: files,  Next: exclude,  Prev: Selecting Archive Members,  Up: Choosing
+
+6.3 Reading Names from a File
+=============================
+
+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
+`--files-from=FILE-OF-NAMES' (`-T FILE-OF-NAMES') option to `tar'.
+Give the name of the file which contains the list of files to include
+as the argument to `--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 `find' utility.
+
+`--files-from=FILE-NAME'
+`-T FILE-NAME'
+     Get names to extract or create from file FILE-NAME.
+
+   If you give a single dash as a file name for `--files-from', (i.e.,
+you specify either `--files-from=-' or `-T -'), then the file names are
+read from standard input.
+
+   Unless you are running `tar' with `--create', you can not use both
+`--files-from=-' and `--file=-' (`-f -') in the same command.
+
+   Any number of `-T' options can be given in the command line.
+
+   The following example shows how to use `find' to generate a list of
+files smaller than 400K in length and put that list into a file called
+`small-files'.  You can then use the `-T' option to `tar' to specify
+the files from that file, `small-files', to create the archive
+`little.tgz'.  (The `-z' option to `tar' compresses the archive with
+`gzip'; *note gzip:: for more information.)
+
+     $ find .  -size -400 -print > small-files
+     $ tar -c -v -z -T small-files -f little.tgz
+
+In the file list given by `-T' option, any file name beginning with `-'
+character is considered a `tar' option and is processed accordingly.(1)
+For example, the common use of this feature is to change to another
+directory by specifying `-C' option:
+
+     $ cat list
+     -C/etc
+     passwd
+     hosts
+     -C/lib
+     libc.a
+     $ tar -c -f foo.tar --files-from list
+
+In this example, `tar' will first switch to `/etc' directory and add
+files `passwd' and `hosts' to the archive.  Then it will change to
+`/lib' directory and will archive the file `libc.a'.  Thus, the
+resulting archive `foo.tar' will contain:
+
+     $ tar tf foo.tar
+     passwd
+     hosts
+     libc.a
+
+
+   Notice that the option parsing algorithm used with `-T' is stricter
+than the one used by shell.  Namely, when specifying option arguments,
+you should observe the following rules:
+
+   * When using short (single-letter) option form, its argument must
+     immediately follow the option letter, without any intervening
+     whitespace.  For example: `-Cdir'.
+
+   * 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: `--directory=dir'.
+
+   * For both short and long option forms, the option argument can be
+     given on the next line after the option name, e.g.:
+
+          --directory
+          dir
+
+     and
+
+          -C
+          dir
+
+   If you happen to have a file whose name starts with `-', precede it
+with `--add-file' option to prevent it from being recognized as an
+option.  For example: `--add-file=--my-file'.
+
+* Menu:
+
+* nul::
+
+   ---------- Footnotes ----------
+
+   (1) Versions of GNU `tar' up to 1.15.1 recognized only `-C' option
+in file lists, and only if the option and its argument occupied two
+consecutive lines.
+
+
+File: tar.info,  Node: nul,  Up: files
+
+6.3.1 `NUL' Terminated File Names
+---------------------------------
+
+The `--null' option causes `--files-from=FILE-OF-NAMES' (`-T
+FILE-OF-NAMES') to read file names terminated by a `NUL' instead of a
+newline, so files whose names contain newlines can be archived using
+`--files-from'.
+
+`--null'
+     Only consider `NUL' terminated file names, instead of files that
+     terminate in a newline.
+
+   The `--null' option is just like the one in GNU `xargs' and `cpio',
+and is useful with the `-print0' predicate of GNU `find'.  In `tar',
+`--null' also disables special handling for file names that begin with
+dash.
+
+   This example shows how to use `find' to generate a list of files
+larger than 800K in length and put that list into a file called
+`long-files'.  The `-print0' option to `find' is just like `-print',
+except that it separates files with a `NUL' rather than with a newline.
+You can then run `tar' with both the `--null' and `-T' options to
+specify that `tar' get the files from that file, `long-files', to
+create the archive `big.tgz'.  The `--null' option to `tar' will cause
+`tar' to recognize the `NUL' separator between files.
+
+     $ find .  -size +800 -print0 > long-files
+     $ tar -c -v --null --files-from=long-files --file=big.tar
+
+
+File: tar.info,  Node: exclude,  Next: wildcards,  Prev: files,  Up: Choosing
+
+6.4 Excluding Some Files
+========================
+
+     _(This message will disappear, once this node revised.)_
+
+To avoid operating on files whose names match a particular pattern, use
+the `--exclude' or `--exclude-from' options.
+
+`--exclude=PATTERN'
+     Causes `tar' to ignore files that match the PATTERN.
+
+   The `--exclude=PATTERN' option prevents any file or member whose
+name matches the shell wildcard (PATTERN) from being operated on.  For
+example, to create an archive with all the contents of the directory
+`src' except for files whose names end in `.o', use the command `tar
+-cf src.tar --exclude='*.o' src'.
+
+   You may give multiple `--exclude' options.
+
+`--exclude-from=FILE'
+`-X FILE'
+     Causes `tar' to ignore files that match the patterns listed in
+     FILE.
+
+   Use the `--exclude-from' option to read a list of patterns, one per
+line, from FILE; `tar' will ignore files matching those patterns.  Thus
+if `tar' is called as `tar -c -X foo .' and the file `foo' contains a
+single line `*.o', no files whose names end in `.o' will be added to
+the archive.
+
+   When creating an archive, the `--exclude-caches' option family
+causes `tar' to exclude all directories that contain a "cache directory
+tag". A cache directory tag is a short file with the well-known name
+`CACHEDIR.TAG' and having a standard header specified in
+`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 `exclude-caches' option, providing a different
+exclusion semantics:
+
+`--exclude-caches'
+     Do not archive the contents of the directory, but archive the
+     directory itself and the `CACHEDIR.TAG' file.
+
+`--exclude-caches-under'
+     Do not archive the contents of the directory, nor the
+     `CACHEDIR.TAG' file, archive only the directory itself.
+
+`--exclude-caches-all'
+     Omit directories containing `CACHEDIR.TAG' file entirely.
+
+   Another option family, `--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 `exclude-caches', there are three options in this option
+family:
+
+`--exclude-tag=FILE'
+     Do not dump the contents of the directory, but dump the directory
+     itself and the FILE.
+
+`--exclude-tag-under=FILE'
+     Do not dump the contents of the directory, nor the FILE, archive
+     only the directory itself.
+
+`--exclude-tag-all=FILE'
+     Omit directories containing FILE file entirely.
+
+   Multiple `--exclude-tag*' options can be given.
+
+   For example, given this directory:
+
+     $ find dir
+     dir
+     dir/blues
+     dir/jazz
+     dir/folk
+     dir/folk/tagfile
+     dir/folk/sanjuan
+     dir/folk/trote
+
+   The `--exclude-tag' will produce the following:
+
+     $ 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
+
+   Both the `dir/folk' directory and its tagfile are preserved in the
+archive, however the rest of files in this directory are not.
+
+   Now, using the `--exclude-tag-under' option will exclude `tagfile'
+from the dump, while still preserving the directory itself, as shown in
+this example:
+
+     $ 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
+
+   Finally, using `--exclude-tag-all' omits the `dir/folk' directory
+entirely:
+
+     $ 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
+
+* Menu:
+
+* problems with exclude::
+
+
+File: tar.info,  Node: problems with exclude,  Up: exclude
+
+Problems with Using the `exclude' Options
+-----------------------------------------
+
+Some users find `exclude' options confusing.  Here are some common
+pitfalls:
+
+   * The main operating mode of `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 `*.o', but explicitly name
+     the file `dir.o/foo' after all the options have been listed,
+     `dir.o/foo' will be excluded from the archive.
+
+   * You can sometimes confuse the meanings of `--exclude' and
+     `--exclude-from'.  Be careful: use `--exclude' when files to be
+     excluded are given as a pattern on the command line.  Use
+     `--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.
+
+   * When you use `--exclude=PATTERN', be sure to quote the PATTERN
+     parameter, so GNU `tar' sees wildcard characters like `*'.  If you
+     do not do this, the shell might expand the `*' itself using files
+     at hand, so `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:
+
+          $ tar -c -f ARCHIVE.TAR --exclude '*.o' DIRECTORY
+
+     rather than:
+
+          # _Wrong!_
+          $ tar -c -f ARCHIVE.TAR --exclude *.o DIRECTORY
+
+   * You must use use shell syntax, or globbing, rather than `regexp'
+     syntax, when using exclude options in `tar'.  If you try to use
+     `regexp' syntax to describe files to be excluded, your command
+     might fail.
+
+   *  In earlier versions of `tar', what is now the `--exclude-from'
+     option was called `--exclude' instead.  Now, `--exclude' applies
+     to patterns listed on the command line and `--exclude-from'
+     applies to patterns listed in a file.
+
+
+
+File: tar.info,  Node: wildcards,  Next: quoting styles,  Prev: exclude,  Up: Choosing
+
+6.5 Wildcards Patterns and Matching
+===================================
+
+"Globbing" is the operation by which "wildcard" characters, `*' or `?'
+for example, are replaced and expanded into all existing files matching
+the given pattern.  GNU `tar' 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 `tar' archives.  This section has the purpose of explaining wildcard
+syntax for `tar'.
+
+   A 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: `a' will
+match only `a', and not `A'.  The character `?' in the pattern matches
+any single character in the matched string.  The character `*' in the
+pattern matches zero, one, or more single characters in the matched
+string.  The character `\' says to take the following character of the
+pattern _literally_; it is useful when one needs to match the `?', `*',
+`[' or `\' characters, themselves.
+
+   The character `[', up to the matching `]', introduces a character
+class.  A "character class" is a list of acceptable characters for the
+next single character of the matched string.  For example, `[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 `\' lose their special meaning; for example, `[-\\[*?]]'
+would match any of the characters, `-', `\', `[', `*', `?', or `]'.
+(Due to parsing constraints, the characters `-' and `]' must either
+come _first_ or _last_ in a character class.)
+
+   If the first character of the class after the opening `[' is `!' or
+`^', then the meaning of the class is reversed.  Rather than listing
+character to match, it lists those characters which are _forbidden_ as
+the next single character of the matched string.
+
+   Other characters of the class stand for themselves.  The special
+construction `[A-E]', using an hyphen between two letters, is meant to
+represent all characters between A and E, inclusive.
+
+   Periods (`.') or forward slashes (`/') 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::
+
+
+File: tar.info,  Node: controlling pattern-matching,  Up: wildcards
+
+Controlling Pattern-Matching
+----------------------------
+
+For the purposes of this section, we call "exclusion members" all
+member names obtained while processing `--exclude' and `--exclude-from'
+options, and "inclusion members" those member names that were given in
+the command line or read from the file specified with `--files-from'
+option.
+
+   These two pairs of member lists are used in the following operations:
+`--diff', `--extract', `--list', `--update'.
+
+   There are no inclusion members in create mode (`--create' and
+`--append'), since in this mode the names obtained from the command
+line refer to _files_, not archive members.
+
+   By default, inclusion members are compared with archive members
+literally (1) and exclusion members are treated as globbing patterns.
+For example:
+
+     $ tar tf foo.tar
+     a.c
+     b.c
+     a.txt
+     [remarks]
+     # Member names are used verbatim:
+     $ tar -xf foo.tar -v '[remarks]'
+     [remarks]
+     # Exclude member names are globbed:
+     $ tar -xf foo.tar -v --exclude '*.c'
+     a.txt
+     [remarks]
+
+   This behavior can be altered by using the following options:
+
+`--wildcards'
+     Treat all member names as wildcards.
+
+`--no-wildcards'
+     Treat all member names as literal strings.
+
+   Thus, to extract files whose names end in `.c', you can use:
+
+     $ tar -xf foo.tar -v --wildcards '*.c'
+     a.c
+     b.c
+
+Notice quoting of the pattern to prevent the shell from interpreting it.
+
+   The effect of `--wildcards' option is canceled by `--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:
+
+     $ tar -xf foo.tar --wildcards '*.txt' --no-wildcards '[remarks]'
+
+instructs `tar' to extract from `foo.tar' all files whose names end in
+`.txt' and the file named `[remarks]'.
+
+   Normally, a pattern matches a name if an initial subsequence of the
+name's components matches the pattern, where `*', `?', and `[...]' are
+the usual shell wildcards, `\' escapes wildcards, and wildcards can
+match `/'.
+
+   Other than optionally stripping leading `/' from names (*note
+absolute::), patterns and names are used as-is.  For example, trailing
+`/' 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:
+
+     --ignore-case --exclude='makefile' --no-ignore-case ---exclude='readme'
+
+ignores case when excluding `makefile', but not when excluding `readme'.
+
+`--anchored'
+`--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 `--no-anchored' for exclusion members and
+     `--anchored' inclusion members.
+
+`--ignore-case'
+`--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.
+
+`--wildcards-match-slash'
+`--no-wildcards-match-slash'
+     When wildcards match slash (the default for exclusion members), a
+     wildcard like `*' in the pattern can match a `/' in the name.
+     Otherwise, `/' is matched only by `/'.
+
+
+   The `--recursion' and `--no-recursion' options (*note 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:
+
+Members                Default settings
+-------------------------------------------------------------------------- 
+Inclusion              `--no-wildcards --anchored
+                       --no-wildcards-match-slash'
+Exclusion              `--wildcards --no-anchored
+                       --wildcards-match-slash'
+
+   ---------- Footnotes ----------
+
+   (1) Notice that earlier GNU `tar' versions used globbing for
+inclusion members, which contradicted to UNIX98 specification and was
+not documented. *Note Changes::, for more information on this and other
+changes.
+
+
+File: tar.info,  Node: quoting styles,  Next: transform,  Prev: wildcards,  Up: Choosing
+
+6.6 Quoting Member Names
+========================
+
+When displaying member names, `tar' takes care to avoid ambiguities
+caused by certain characters.  This is called "name quoting".  The
+characters in question are:
+
+   * Non-printable control characters:
+
+     Character     ASCII   Character name
+     --------------------------------------------------------------- 
+     \a            7       Audible bell
+     \b            8       Backspace
+     \f            12      Form feed
+     \n            10      New line
+     \r            13      Carriage return
+     \t            9       Horizontal tabulation
+     \v            11      Vertical tabulation
+
+   * Space (ASCII 32)
+
+   * Single and double quotes (`'' and `"')
+
+   * Backslash (`\')
+
+   The exact way `tar' uses to quote these characters depends on the
+"quoting style".  The default quoting style, called "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 `Character' in the above table, a space
+is printed as `\ ' and a backslash as `\\'.
+
+   GNU `tar' offers seven distinct quoting styles, which can be selected
+using `--quoting-style' option:
+
+`--quoting-style=STYLE'
+     Sets quoting style.  Valid values for STYLE argument are: literal,
+     shell, shell-always, c, escape, locale, clocale.
+
+   These styles are described in detail below.  To illustrate their
+effect, we will use an imaginary tar archive `arch.tar' containing the
+following members:
+
+     # 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
+
+   Here is how usual `ls' command would have listed them, if they had
+existed in the current working directory:
+
+     $ ls
+     a\ttab
+     a\nnewline
+     a\ space
+     a"double"quote
+     a'single'quote
+     a\\backslash
+
+   Quoting styles:
+
+`literal'
+     No quoting, display each character as is:
+
+          $ tar tf arch.tar --quoting-style=literal
+          ./
+          ./a space
+          ./a'single'quote
+          ./a"double"quote
+          ./a\backslash
+          ./a	tab
+          ./a
+          newline
+
+`shell'
+     Display characters the same way Bourne shell does: control
+     characters, except `\t' and `\n', are printed using backslash
+     escapes, `\t' and `\n' are printed as is, and a single quote is
+     printed as `\''.  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:
+
+          $ tar tf arch.tar --quoting-style=shell
+          ./
+          './a space'
+          './a'\''single'\''quote'
+          './a"double"quote'
+          './a\backslash'
+          './a	tab'
+          './a
+          newline'
+
+`shell-always'
+     Same as `shell', but the names are always enclosed in single
+     quotes:
+
+          $ tar tf arch.tar --quoting-style=shell-always
+          './'
+          './a space'
+          './a'\''single'\''quote'
+          './a"double"quote'
+          './a\backslash'
+          './a	tab'
+          './a
+          newline'
+
+`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 `\"',
+     backslash characters are represented as `\\'.  Single quotes and
+     spaces are not quoted:
+
+          $ tar tf arch.tar --quoting-style=c
+          "./"
+          "./a space"
+          "./a'single'quote"
+          "./a\"double\"quote"
+          "./a\\backslash"
+          "./a\ttab"
+          "./a\nnewline"
+
+`escape'
+     Control characters are printed using backslash notation, a space is
+     printed as `\ ' and a backslash as `\\'.  This is the default
+     quoting style, unless it was changed when configured the package.
+
+          $ tar tf arch.tar --quoting-style=escape
+          ./
+          ./a space
+          ./a'single'quote
+          ./a"double"quote
+          ./a\\backslash
+          ./a\ttab
+          ./a\nnewline
+
+`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 ``' as left and `'' as right quotation
+     marks.  Any occurrences of the right quotation mark in a name are
+     escaped with `\', for example:
+
+     For example:
+
+          $ tar tf arch.tar --quoting-style=locale
+          `./'
+          `./a space'
+          `./a\'single\'quote'
+          `./a"double"quote'
+          `./a\\backslash'
+          `./a\ttab'
+          `./a\nnewline'
+
+`clocale'
+     Same as `locale', but `"' is used for both left and right
+     quotation marks, if not provided by the currently selected locale:
+
+          $ tar tf arch.tar --quoting-style=clocale
+          "./"
+          "./a space"
+          "./a'single'quote"
+          "./a\"double\"quote"
+          "./a\\backslash"
+          "./a\ttab"
+          "./a\nnewline"
+
+   You can specify which characters should be quoted in addition to
+those implied by the current quoting style:
+
+`--quote-chars=STRING'
+     Always quote characters from STRING, even if the selected quoting
+     style would not quote them.
+
+   For example, using `escape' quoting (compare with the usual escape
+listing above):
+
+     $ tar tf arch.tar --quoting-style=escape --quote-chars=' "'
+     ./
+     ./a\ space
+     ./a'single'quote
+     ./a\"double\"quote
+     ./a\\backslash
+     ./a\ttab
+     ./a\nnewline
+
+   To disable quoting of such additional characters, use the following
+option:
+
+`--no-quote-chars=STRING'
+     Remove characters listed in STRING from the list of quoted
+     characters set by the previous `--quote-chars' option.
+
+   This option is particularly useful if you have added `--quote-chars'
+to your `TAR_OPTIONS' (*note TAR_OPTIONS::) and wish to disable it for
+the current invocation.
+
+   Note, that `--no-quote-chars' does _not_ disable those characters
+that are quoted by default in the selected quoting style.
+
+
+File: tar.info,  Node: transform,  Next: after,  Prev: quoting styles,  Up: Choosing
+
+6.7 Modifying File and Member Names
+===================================
+
+`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 `../'.  GNU `tar' takes
+special precautions when extracting such names and provides a special
+option for handling them, which is described in *note 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.
+
+   GNU `tar' provides two options for these needs.
+
+`--strip-components=NUMBER'
+     Strip given NUMBER of leading components from file names before
+     extraction.
+
+   For example, suppose you have archived whole `/usr' hierarchy to a
+tar archive named `usr.tar'.  Among other files, this archive contains
+`usr/include/stdlib.h', which you wish to extract to the current
+working directory.  To do so, you type:
+
+     $ tar -xf usr.tar --strip=2 usr/include/stdlib.h
+
+   The option `--strip=2' instructs `tar' to strip the two leading
+components (`usr/' and `include/') off the file name.
+
+   If you add to the above invocation `--verbose' (`-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 `tar' provides a special option for altering this
+behavior:
+
+`--show-transformed-names'
+     Display file or member names with all requested transformations
+     applied.
+
+For example:
+
+     $ tar -xf usr.tar -v --strip=2 usr/include/stdlib.h
+     usr/include/stdlib.h
+     $ tar -xf usr.tar -v --strip=2 --show-transformed usr/include/stdlib.h
+     stdlib.h
+
+   Notice that in both cases the file is `stdlib.h' extracted to the
+current working directory, `--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
+
+     $ tar -x --strip=N
+
+it is often advisable to run
+
+     $ tar -t -v --show-transformed --strip=N
+
+to make sure the command will produce the intended results.
+
+   In case you need to apply more complex modifications to the file
+name, GNU `tar' provides a general-purpose transformation option:
+
+`--transform=EXPRESSION'
+     Modify file names using supplied EXPRESSION.
+
+The EXPRESSION is a `sed'-like replace expression of the form:
+
+     s/REGEXP/REPLACE/[FLAGS]
+
+where REGEXP is a "regular expression", REPLACE is a replacement for
+each file name part that matches REGEXP.  Both REGEXP and REPLACE are
+described in detail in *note The "s" Command: (sed)The "s" Command.
+
+   Supported FLAGS are:
+
+`g'
+     Apply the replacement to _all_ matches to the REGEXP, not just the
+     first.
+
+`i'
+     Use case-insensitive matching
+
+`x'
+     REGEXP is an "extended regular expression" (*note Extended regular
+     expressions: (sed)Extended regexps.).
+
+`NUMBER'
+     Only replace the NUMBERth match of the REGEXP.
+
+     Note: the POSIX standard does not specify what should happen when
+     you mix the `g' and NUMBER modifiers.  GNU `tar' follows the GNU
+     `sed' implementation in this regard, so the interaction is defined
+     to be: ignore matches before the NUMBERth, and then match and
+     replace all matches from the NUMBERth on.
+
+
+   Any delimiter can be used in lieue of `/', the only requirement being
+that it be used consistently throughout the expression. For example,
+the following two expressions are equivalent:
+
+     s/one/two/
+     s,one,two,
+
+   Changing delimiters is often useful when the REGEX contains slashes.
+For example, it is more convenient to write `s,/,-,' than `s/\//-/'.
+
+   Here are several examples of `--transform' usage:
+
+  1. Extract `usr/' hierarchy into `usr/local/':
+
+          $ tar --transform='s,usr/,usr/local/,' -x -f arch.tar
+
+  2. Strip two leading directory components (equivalent to
+     `--strip-components=2'):
+
+          $ tar --transform='s,/*[^/]*/[^/]*/,,' -x -f arch.tar
+
+  3. Prepend `/prefix/'  to each file name:
+
+          $ tar --transform 's,^,/prefix/,' -x -f arch.tar
+
+  4. Convert each file name to lower case:
+
+          $ tar --transform 's/.*/\L&/' -x -f arch.tar
+
+
+   Unlike `--strip-components', `--transform' can be used in any GNU
+`tar' operation mode.  For example, the following command adds files to
+the archive while replacing the leading `usr/' component with `var/':
+
+     $ tar -cf arch.tar --transform='s,^usr/,var/,' /
+
+   To test `--transform' effect we suggest using
+`--show-transformed-names' option:
+
+     $ tar -cf arch.tar --transform='s,^usr/,var/,' \
+            --verbose --show-transformed-names /
+
+   If both `--strip-components' and `--transform' are used together,
+then `--transform' is applied first, and the required number of
+components is then stripped from its result.
+
+
+File: tar.info,  Node: after,  Next: recurse,  Prev: transform,  Up: Choosing
+
+6.8 Operating Only on New Files
+===============================
+
+     _(This message will disappear, once this node revised.)_
+
+The `--after-date=DATE' (`--newer=DATE', `-N DATE') option causes `tar'
+to only work on files whose data modification or status change times
+are newer than the DATE given.  If DATE starts with `/' or `.', 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
+`--after-date' when extracting an archive, `tar' will only extract
+files newer than the DATE you specify.
+
+   If you only want `tar' to make the date comparison based on
+modification of the file's data (rather than status changes), then use
+the `--newer-mtime=DATE' option.
+
+   You may use these options with any operation.  Note that these
+options differ from the `--update' (`-u') operation in that they allow
+you to specify a particular date against which `tar' can compare when
+deciding whether or not to archive the files.
+
+`--after-date=DATE'
+`--newer=DATE'
+`-N DATE'
+     Only store files newer than DATE.
+
+     Acts on files only if their data modification or status change
+     times are later than DATE.  Use in conjunction with any operation.
+
+     If DATE starts with `/' or `.', it is taken to be a file name; the
+     data modification time of that file is used as the date.
+
+`--newer-mtime=DATE'
+     Acts like `--after-date', but only looks at data modification
+     times.
+
+   These options limit `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 *note Date input formats::; remember that the
+entire date argument must be quoted if it contains any spaces.)
+
+   Gurus would say that `--after-date' tests both the data modification
+time (`mtime', the time the contents of the file were last modified)
+and the status change time (`ctime', the time the file's status was
+last changed: owner, permissions, etc.)  fields, while `--newer-mtime'
+tests only the `mtime' field.
+
+   To be precise, `--after-date' checks _both_ `mtime' and `ctime' and
+processes the file if either one is more recent than DATE, while
+`--newer-mtime' only checks `mtime' and disregards `ctime'.  Neither
+does it use `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:
+
+     $ tar -cf foo.tar --newer-mtime '2 days ago'
+
+   When any of these options is used with the option `--verbose' (*note
+verbose tutorial::) GNU `tar' 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, `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:
+
+     $ 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
+
+     *Please Note:* `--after-date' and `--newer-mtime' should not be
+     used for incremental backups.  *Note Incremental Dumps::, for
+     proper way of creating incremental backups.
+
+
+File: tar.info,  Node: recurse,  Next: one,  Prev: after,  Up: Choosing
+
+6.9 Descending into Directories
+===============================
+
+     _(This message will disappear, once this node revised.)_
+
+Usually, `tar' will recursively explore all directories (either those
+given on the command line or through the `--files-from' option) for the
+various files they contain.  However, you may not always want `tar' to
+act this way.
+
+   The `--no-recursion' option inhibits `tar''s recursive descent into
+specified directories.  If you specify `--no-recursion', you can use
+the `find' utility for hunting through levels of directories to
+construct a list of file names which you could then pass to `tar'.
+`find' allows you to be more selective when choosing which files to
+archive; see *note files::, for more information on using `find' with
+`tar', or look.
+
+`--no-recursion'
+     Prevents `tar' from recursively descending directories.
+
+`--recursion'
+     Requires `tar' to recursively descend directories.  This is the
+     default.
+
+   When you use `--no-recursion', GNU `tar' grabs directory entries
+themselves, but does not descend on them recursively.  Many people use
+`find' for locating files they want to back up, and since `tar'
+_usually_ recursively descends on directories, they have to use the
+`-not -type d' test in their `find' invocation (*note Type:
+(find)Type.), as they usually do not want all the files in a directory.
+They then use the `--files-from' option to archive the files located
+via `find'.
+
+   The problem when restoring files archived in this manner is that the
+directories themselves are not in the archive; so the
+`--same-permissions' (`--preserve-permissions', `-p') option does not
+affect them--while users might really like it to.  Specifying
+`--no-recursion' is a way to tell `tar' to grab only the directory
+entries given to it, adding no new files on its own.  To summarize, if
+you use `find' to create a list of files to be stored in an archive,
+use it as follows:
+
+     $ find DIR TESTS | \
+       tar -cf ARCHIVE -T - --no-recursion
+
+   The `--no-recursion' option also applies when extracting: it causes
+`tar' to extract only the matched directory entries, not the files
+under those directories.
+
+   The `--no-recursion' option also affects how globbing patterns are
+interpreted (*note controlling pattern-matching::).
+
+   The `--no-recursion' and `--recursion' options apply to later
+options and operands, and can be overridden by later occurrences of
+`--no-recursion' and `--recursion'.  For example:
+
+     $ tar -cf jams.tar --no-recursion grape --recursion grape/concord
+
+creates an archive with one entry for `grape', and the recursive
+contents of `grape/concord', but no entries under `grape' other than
+`grape/concord'.
+
+
+File: tar.info,  Node: one,  Prev: recurse,  Up: Choosing
+
+6.10 Crossing File System Boundaries
+====================================
+
+     _(This message will disappear, once this node revised.)_
+
+`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 `tar' and specifying `--one-file-system'.
+This option only affects files that are archived because they are in a
+directory that is being archived; `tar' will still archive files
+explicitly named on the command line or through `--files-from',
+regardless of where they reside.
+
+`--one-file-system'
+     Prevents `tar' from crossing file system boundaries when
+     archiving.  Use in conjunction with any write operation.
+
+   The `--one-file-system' option causes `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
+`tar' will not archive that file.  If the file is a directory itself,
+`tar' will not archive anything beneath it; in other words, `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
+`--verbose' (`-v'), files that are excluded are mentioned by name on
+the standard error.
+
+* Menu:
+
+* directory::                   Changing Directory
+* absolute::                    Absolute File Names
+
+
+File: tar.info,  Node: directory,  Next: absolute,  Up: one
+
+6.10.1 Changing the Working Directory
+-------------------------------------
+
+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 `--files-from'
+(`-T'), use `--directory' (`-C').  This will change the working
+directory to the specified directory after that point in the list.
+
+`--directory=DIRECTORY'
+`-C DIRECTORY'
+     Changes the working directory in the middle of a command line.
+
+   For example,
+
+     $ tar -c -f jams.tar grape prune -C food cherry
+
+will place the files `grape' and `prune' from the current directory
+into the archive `jams.tar', followed by the file `cherry' from the
+directory `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 `cherry' is recorded in the archive under the
+precise name `cherry', _not_ `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 `tar --extract', all
+three files will be written in the current directory.
+
+   Contrast this with the command,
+
+     $ tar -c -f jams.tar grape prune -C food red/cherry
+
+which records the third file in the archive under the name `red/cherry'
+so that, if the archive is extracted using `tar --extract', the third
+file will be written in a subdirectory named `orange-colored'.
+
+   You can use the `--directory' option to make the archive independent
+of the original name of the directory holding the files.  The following
+command places the files `/etc/passwd', `/etc/hosts', and `/lib/libc.a'
+into the archive `foo.tar':
+
+     $ tar -c -f foo.tar -C /etc passwd hosts -C /lib libc.a
+
+However, the names of the archive members will be exactly what they were
+on the command line: `passwd', `hosts', and `libc.a'.  They will not
+appear to be related by file name to the original directories where
+those files were located.
+
+   Note that `--directory' options are interpreted consecutively.  If
+`--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 `tar', due to a previous
+`--directory' option.
+
+   When using `--files-from' (*note files::), you can put various `tar'
+options (including `-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:
+
+     -C/etc
+     passwd
+     hosts
+     --directory=/lib
+     libc.a
+
+To use it, you would invoke `tar' as follows:
+
+     $ tar -c -f foo.tar --files-from list
+
+   The interpretation of `--directory' is disabled by `--null' option.
+
+
+File: tar.info,  Node: absolute,  Prev: directory,  Up: one
+
+6.10.2 Absolute File Names
+--------------------------
+
+     _(This message will disappear, once this node revised.)_
+
+`--absolute-names'
+`-P'
+     Do not strip leading slashes from file names, and permit file names
+     containing a `..' file name component.
+
+   By default, GNU `tar' drops a leading `/' on input or output, and
+complains about file names containing a `..' component.  This option
+turns off this behavior.
+
+   When `tar' extracts archive members from an archive, it strips any
+leading slashes (`/') 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
+`/etc/passwd', `tar' will extract it as if the name were really
+`etc/passwd'.
+
+   File names containing `..' can cause problems when extracting, so
+`tar' normally warns you about such files when creating an archive, and
+rejects attempts to extracts such files.
+
+   Other `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-GNU `tar' program to use.  Therefore, GNU
+`tar' also strips leading slashes from member names when putting
+members into the archive.  For example, if you ask `tar' to add the file
+`/bin/ls' to an archive, it will do so, but the member name will be
+`bin/ls'.(1)
+
+   If you use the `--absolute-names' (`-P') option, `tar' will do none
+of these transformations.
+
+   To archive or extract files relative to the root directory, specify
+the `--absolute-names' (`-P') option.
+
+   Normally, `tar' acts on files relative to the working
+directory--ignoring superior directory names when archiving, and
+ignoring leading slashes when extracting.
+
+   When you specify `--absolute-names' (`-P'), `tar' stores file names
+including all superior directory names, and preserves leading slashes.
+If you only invoked `tar' from the root directory you would never need
+the `--absolute-names' option, but using this option may be more
+convenient than switching to root.
+
+`--absolute-names'
+     Preserves full file names (including superior directory names) when
+     archiving files.  Preserves leading slash when extracting files.
+
+
+   `tar' prints out a message about removing the `/' from file names.
+This message appears once per GNU `tar' 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 `tar' standard
+error to the sink.  For example, under `sh':
+
+     $ tar -c -f archive.tar /home 2> /dev/null
+
+Another solution, both nicer and simpler, would be to change to the `/'
+directory first, and then avoid absolute notation.  For example:
+
+     $ (cd / && tar -c -f archive.tar home)
+     # or:
+     $ tar -c -f archive.tar -C  / home
+
+   ---------- Footnotes ----------
+
+   (1) A side effect of this is that when `--create' is used with
+`--verbose' the resulting output is not, generally speaking, the same
+as the one you'd get running `tar --list' command.  This may be
+important if you use some scripts for comparing both outputs.  *Note
+listing member and file names::, for the information on how to handle
+this case.
+
+
+File: tar.info,  Node: Date input formats,  Next: Formats,  Prev: Choosing,  Up: Top
+
+7 Date input formats
+********************
+
+First, a quote:
+
+     Our units of temporal measurement, from seconds on up to months,
+     are so complicated, asymmetrical and disjunctive so as to make
+     coherent mental reckoning in time all but impossible.  Indeed, had
+     some tyrannical god contrived to enslave our minds to time, to
+     make it all but impossible for us to escape subjection to sodden
+     routines and unpleasant surprises, he could hardly have done
+     better than handing down our present system.  It is like a set of
+     trapezoidal building blocks, with no vertical or horizontal
+     surfaces, like a language in which the simplest thought demands
+     ornate constructions, useless particles and lengthy
+     circumlocutions.  Unlike the more successful patterns of language
+     and science, which enable us to face experience boldly or at least
+     level-headedly, our system of temporal calculation silently and
+     persistently encourages our terror of time.
+
+     ...  It is as though architects had to measure length in feet,
+     width in meters and height in ells; as though basic instruction
+     manuals demanded a knowledge of five different languages.  It is
+     no wonder then that we often look into our own immediate past or
+     future, last Tuesday or a week from Sunday, with feelings of
+     helpless confusion.  ...
+
+     -- Robert Grudin, `Time and the Art of Living'.
+
+   This section describes the textual date representations that GNU
+programs accept.  These are the strings you, as a user, can supply as
+arguments to the various programs.  The C interface (via the `get_date'
+function) is not described here.
+
+* Menu:
+
+* General date syntax::            Common rules.
+* Calendar date items::            19 Dec 1994.
+* Time of day items::              9:20pm.
+* Time zone items::                EST, PDT, 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.
+
+
+File: tar.info,  Node: General date syntax,  Next: Calendar date items,  Up: Date input formats
+
+7.1 General date syntax
+=======================
+
+A "date" is a string, possibly empty, containing many items separated
+by whitespace.  The whitespace may be omitted when no ambiguity arises.
+The empty string means the beginning of today (i.e., midnight).  Order
+of the items is immaterial.  A date string may contain many flavors of
+items:
+
+   * calendar date items
+
+   * time of day items
+
+   * time zone items
+
+   * day of the week items
+
+   * relative items
+
+   * pure numbers.
+
+We describe each of these item types in turn, below.
+
+   A few ordinal numbers may be written out in words in some contexts.
+This is most useful for specifying day of the week items or relative
+items (see below).  Among the most commonly used ordinal numbers, the
+word `last' stands for -1, `this' stands for 0, and `first' and `next'
+both stand for 1.  Because the word `second' stands for the unit of
+time there is no way to write the ordinal number 2, but for convenience
+`third' stands for 3, `fourth' for 4, `fifth' for 5, `sixth' for 6,
+`seventh' for 7, `eighth' for 8, `ninth' for 9, `tenth' for 10,
+`eleventh' for 11 and `twelfth' for 12.
+
+   When a month is written this way, it is still considered to be
+written numerically, instead of being "spelled in full"; this changes
+the allowed strings.
+
+   In the current implementation, only English is supported for words
+and abbreviations like `AM', `DST', `EST', `first', `January',
+`Sunday', `tomorrow', and `year'.
+
+   The output of the `date' command is not always acceptable as a date
+string, not only because of the language problem, but also because
+there is no standard meaning for time zone items like `IST'.  When using
+`date' to generate a date string intended to be parsed later, specify a
+date format that is independent of language and that does not use time
+zone items other than `UTC' and `Z'.  Here are some ways to do this:
+
+     $ LC_ALL=C TZ=UTC0 date
+     Mon Mar  1 00:21:42 UTC 2004
+     $ TZ=UTC0 date +'%Y-%m-%d %H:%M:%SZ'
+     2004-03-01 00:21:42Z
+     $ date --iso-8601=ns | tr T ' '  # --iso-8601 is a GNU extension.
+     2004-02-29 16:21:42,692722128-0800
+     $ date --rfc-2822  # a GNU extension
+     Sun, 29 Feb 2004 16:21:42 -0800
+     $ date +'%Y-%m-%d %H:%M:%S %z'  # %z is a GNU extension.
+     2004-02-29 16:21:42 -0800
+     $ date +'@%s.%N'  # %s and %N are GNU extensions.
+     @1078100502.692722128
+
+   Alphabetic case is completely ignored in dates.  Comments may be
+introduced between round parentheses, as long as included parentheses
+are properly nested.  Hyphens not followed by a digit are currently
+ignored.  Leading zeros on numbers are ignored.
+
+   Invalid dates like `2005-02-29' or times like `24:00' are rejected.
+In the typical case of a host that does not support leap seconds, a
+time like `23:59:60' is rejected even if it corresponds to a valid leap
+second.
+
+
+File: tar.info,  Node: Calendar date items,  Next: Time of day items,  Prev: General date syntax,  Up: Date input formats
+
+7.2 Calendar date items
+=======================
+
+A "calendar date item" specifies a day of the year.  It is specified
+differently, depending on whether the month is specified numerically or
+literally.  All these strings specify the same calendar date:
+
+     1972-09-24     # ISO 8601.
+     72-9-24        # Assume 19xx for 69 through 99,
+                    # 20xx for 00 through 68.
+     72-09-24       # Leading zeros are ignored.
+     9/24/72        # Common U.S. writing.
+     24 September 1972
+     24 Sept 72     # September has a special abbreviation.
+     24 Sep 72      # Three-letter abbreviations always allowed.
+     Sep 24, 1972
+     24-sep-72
+     24sep72
+
+   The year can also be omitted.  In this case, the last specified year
+is used, or the current year if none.  For example:
+
+     9/24
+     sep 24
+
+   Here are the rules.
+
+   For numeric months, the ISO 8601 format `YEAR-MONTH-DAY' is allowed,
+where YEAR is any positive number, MONTH is a number between 01 and 12,
+and DAY is a number between 01 and 31.  A leading zero must be present
+if a number is less than ten.  If YEAR is 68 or smaller, then 2000 is
+added to it; otherwise, if YEAR is less than 100, then 1900 is added to
+it.  The construct `MONTH/DAY/YEAR', popular in the United States, is
+accepted.  Also `MONTH/DAY', omitting the year.
+
+   Literal months may be spelled out in full: `January', `February',
+`March', `April', `May', `June', `July', `August', `September',
+`October', `November' or `December'.  Literal months may be abbreviated
+to their first three letters, possibly followed by an abbreviating dot.
+It is also permitted to write `Sept' instead of `September'.
+
+   When months are written literally, the calendar date may be given as
+any of the following:
+
+     DAY MONTH YEAR
+     DAY MONTH
+     MONTH DAY YEAR
+     DAY-MONTH-YEAR
+
+   Or, omitting the year:
+
+     MONTH DAY
+
+
+File: tar.info,  Node: Time of day items,  Next: Time zone items,  Prev: Calendar date items,  Up: Date input formats
+
+7.3 Time of day items
+=====================
+
+A "time of day item" in date strings specifies the time on a given day.
+Here are some examples, all of which represent the same time:
+
+     20:02:00.000000
+     20:02
+     8:02pm
+     20:02-0500      # In EST (U.S. Eastern Standard Time).
+
+   More generally, the time of day may be given as
+`HOUR:MINUTE:SECOND', where HOUR is a number between 0 and 23, MINUTE
+is a number between 0 and 59, and SECOND is a number between 0 and 59
+possibly followed by `.' or `,' and a fraction containing one or more
+digits.  Alternatively, `:SECOND' can be omitted, in which case it is
+taken to be zero.  On the rare hosts that support leap seconds, SECOND
+may be 60.
+
+   If the time is followed by `am' or `pm' (or `a.m.' or `p.m.'), HOUR
+is restricted to run from 1 to 12, and `:MINUTE' may be omitted (taken
+to be zero).  `am' indicates the first half of the day, `pm' indicates
+the second half of the day.  In this notation, 12 is the predecessor of
+1: midnight is `12am' while noon is `12pm'.  (This is the zero-oriented
+interpretation of `12am' and `12pm', as opposed to the old tradition
+derived from Latin which uses `12m' for noon and `12pm' for midnight.)
+
+   The time may alternatively be followed by a time zone correction,
+expressed as `SHHMM', where S is `+' or `-', HH is a number of zone
+hours and MM is a number of zone minutes.  You can also separate HH
+from MM with a colon.  When a time zone correction is given this way, it
+forces interpretation of the time relative to Coordinated Universal
+Time (UTC), overriding any previous specification for the time zone or
+the local time zone.  For example, `+0530' and `+05:30' both stand for
+the time zone 5.5 hours ahead of UTC (e.g., India).  The MINUTE part of
+the time of day may not be elided when a time zone correction is used.
+This is the best way to specify a time zone correction by fractional
+parts of an hour.
+
+   Either `am'/`pm' or a time zone correction may be specified, but not
+both.
+
+
+File: tar.info,  Node: Time zone items,  Next: Day of week items,  Prev: Time of day items,  Up: Date input formats
+
+7.4 Time zone items
+===================
+
+A "time zone item" specifies an international time zone, indicated by a
+small set of letters, e.g., `UTC' or `Z' for Coordinated Universal
+Time.  Any included periods are ignored.  By following a
+non-daylight-saving time zone by the string `DST' in a separate word
+(that is, separated by some white space), the corresponding daylight
+saving time zone may be specified.  Alternatively, a
+non-daylight-saving time zone can be followed by a time zone
+correction, to add the two values.  This is normally done only for
+`UTC'; for example, `UTC+05:30' is equivalent to `+05:30'.
+
+   Time zone items other than `UTC' and `Z' are obsolescent and are not
+recommended, because they are ambiguous; for example, `EST' has a
+different meaning in Australia than in the United States.  Instead,
+it's better to use unambiguous numeric time zone corrections like
+`-0500', as described in the previous section.
+
+   If neither a time zone item nor a time zone correction is supplied,
+time stamps are interpreted using the rules of the default time zone
+(*note Specifying time zone rules::).
+
+
+File: tar.info,  Node: Day of week items,  Next: Relative items in date strings,  Prev: Time zone items,  Up: Date input formats
+
+7.5 Day of week items
+=====================
+
+The explicit mention of a day of the week will forward the date (only
+if necessary) to reach that day of the week in the future.
+
+   Days of the week may be spelled out in full: `Sunday', `Monday',
+`Tuesday', `Wednesday', `Thursday', `Friday' or `Saturday'.  Days may
+be abbreviated to their first three letters, optionally followed by a
+period.  The special abbreviations `Tues' for `Tuesday', `Wednes' for
+`Wednesday' and `Thur' or `Thurs' for `Thursday' are also allowed.
+
+   A number may precede a day of the week item to move forward
+supplementary weeks.  It is best used in expression like `third
+monday'.  In this context, `last DAY' or `next DAY' is also acceptable;
+they move one week before or after the day that DAY by itself would
+represent.
+
+   A comma following a day of the week item is ignored.
+
+
+File: tar.info,  Node: Relative items in date strings,  Next: Pure numbers in date strings,  Prev: Day of week items,  Up: Date input formats
+
+7.6 Relative items in date strings
+==================================
+
+"Relative items" adjust a date (or the current date if none) forward or
+backward.  The effects of relative items accumulate.  Here are some
+examples:
+
+     1 year
+     1 year ago
+     3 years
+     2 days
+
+   The unit of time displacement may be selected by the string `year'
+or `month' for moving by whole years or months.  These are fuzzy units,
+as years and months are not all of equal duration.  More precise units
+are `fortnight' which is worth 14 days, `week' worth 7 days, `day'
+worth 24 hours, `hour' worth 60 minutes, `minute' or `min' worth 60
+seconds, and `second' or `sec' worth one second.  An `s' suffix on
+these units is accepted and ignored.
+
+   The unit of time may be preceded by a multiplier, given as an
+optionally signed number.  Unsigned numbers are taken as positively
+signed.  No number at all implies 1 for a multiplier.  Following a
+relative item by the string `ago' is equivalent to preceding the unit
+by a multiplier with value -1.
+
+   The string `tomorrow' is worth one day in the future (equivalent to
+`day'), the string `yesterday' is worth one day in the past (equivalent
+to `day ago').
+
+   The strings `now' or `today' are relative items corresponding to
+zero-valued time displacement, these strings come from the fact a
+zero-valued time displacement represents the current time when not
+otherwise changed by previous items.  They may be used to stress other
+items, like in `12:00 today'.  The string `this' also has the meaning
+of a zero-valued time displacement, but is preferred in date strings
+like `this thursday'.
+
+   When a relative item causes the resulting date to cross a boundary
+where the clocks were adjusted, typically for daylight saving time, the
+resulting date and time are adjusted accordingly.
+
+   The fuzz in units can cause problems with relative items.  For
+example, `2003-07-31 -1 month' might evaluate to 2003-07-01, because
+2003-06-31 is an invalid date.  To determine the previous month more
+reliably, you can ask for the month before the 15th of the current
+month.  For example:
+
+     $ date -R
+     Thu, 31 Jul 2003 13:02:39 -0700
+     $ date --date='-1 month' +'Last month was %B?'
+     Last month was July?
+     $ date --date="$(date +%Y-%m-15) -1 month" +'Last month was %B!'
+     Last month was June!
+
+   Also, take care when manipulating dates around clock changes such as
+daylight saving leaps.  In a few cases these have added or subtracted
+as much as 24 hours from the clock, so it is often wise to adopt
+universal time by setting the `TZ' environment variable to `UTC0'
+before embarking on calendrical calculations.
+
+
+File: tar.info,  Node: Pure numbers in date strings,  Next: Seconds since the Epoch,  Prev: Relative items in date strings,  Up: Date input formats
+
+7.7 Pure numbers in date strings
+================================
+
+The precise interpretation of a pure decimal number depends on the
+context in the date string.
+
+   If the decimal number is of the form YYYYMMDD and no other calendar
+date item (*note Calendar date items::) appears before it in the date
+string, then YYYY is read as the year, MM as the month number and DD as
+the day of the month, for the specified calendar date.
+
+   If the decimal number is of the form HHMM and no other time of day
+item appears before it in the date string, then HH is read as the hour
+of the day and MM as the minute of the hour, for the specified time of
+day.  MM can also be omitted.
+
+   If both a calendar date and a time of day appear to the left of a
+number in the date string, but no relative item, then the number
+overrides the year.
+
+
+File: tar.info,  Node: Seconds since the Epoch,  Next: Specifying time zone rules,  Prev: Pure numbers in date strings,  Up: Date input formats
+
+7.8 Seconds since the Epoch
+===========================
+
+If you precede a number with `@', it represents an internal time stamp
+as a count of seconds.  The number can contain an internal decimal
+point (either `.' or `,'); any excess precision not supported by the
+internal representation is truncated toward minus infinity.  Such a
+number cannot be combined with any other date item, as it specifies a
+complete time stamp.
+
+   Internally, computer times are represented as a count of seconds
+since an epoch--a well-defined point of time.  On GNU and POSIX
+systems, the epoch is 1970-01-01 00:00:00 UTC, so `@0' represents this
+time, `@1' represents 1970-01-01 00:00:01 UTC, and so forth.  GNU and
+most other POSIX-compliant systems support such times as an extension
+to POSIX, using negative counts, so that `@-1' represents 1969-12-31
+23:59:59 UTC.
+
+   Traditional Unix systems count seconds with 32-bit two's-complement
+integers and can represent times from 1901-12-13 20:45:52 through
+2038-01-19 03:14:07 UTC.  More modern systems use 64-bit counts of
+seconds with nanosecond subcounts, and can represent all the times in
+the known lifetime of the universe to a resolution of 1 nanosecond.
+
+   On most hosts, these counts ignore the presence of leap seconds.
+For example, on most hosts `@915148799' represents 1998-12-31 23:59:59
+UTC, `@915148800' represents 1999-01-01 00:00:00 UTC, and there is no
+way to represent the intervening leap second 1998-12-31 23:59:60 UTC.
+
+
+File: tar.info,  Node: Specifying time zone rules,  Next: Authors of get_date,  Prev: Seconds since the Epoch,  Up: Date input formats
+
+7.9 Specifying time zone rules
+==============================
+
+Normally, dates are interpreted using the rules of the current time
+zone, which in turn are specified by the `TZ' environment variable, or
+by a system default if `TZ' is not set.  To specify a different set of
+default time zone rules that apply just to one date, start the date
+with a string of the form `TZ="RULE"'.  The two quote characters (`"')
+must be present in the date, and any quotes or backslashes within RULE
+must be escaped by a backslash.
+
+   For example, with the GNU `date' command you can answer the question
+"What time is it in New York when a Paris clock shows 6:30am on October
+31, 2004?" by using a date beginning with `TZ="Europe/Paris"' as shown
+in the following shell transcript:
+
+     $ export TZ="America/New_York"
+     $ date --date='TZ="Europe/Paris" 2004-10-31 06:30'
+     Sun Oct 31 01:30:00 EDT 2004
+
+   In this example, the `--date' operand begins with its own `TZ'
+setting, so the rest of that operand is processed according to
+`Europe/Paris' rules, treating the string `2004-10-31 06:30' as if it
+were in Paris.  However, since the output of the `date' command is
+processed according to the overall time zone rules, it uses New York
+time.  (Paris was normally six hours ahead of New York in 2004, but
+this example refers to a brief Halloween period when the gap was five
+hours.)
+
+   A `TZ' value is a rule that typically names a location in the `tz'
+database (http://www.twinsun.com/tz/tz-link.htm).  A recent catalog of
+location names appears in the TWiki Date and Time Gateway
+(http://twiki.org/cgi-bin/xtra/tzdate).  A few non-GNU hosts require a
+colon before a location name in a `TZ' setting, e.g.,
+`TZ=":America/New_York"'.
+
+   The `tz' database includes a wide variety of locations ranging from
+`Arctic/Longyearbyen' to `Antarctica/South_Pole', but if you are at sea
+and have your own private time zone, or if you are using a non-GNU host
+that does not support the `tz' database, you may need to use a POSIX
+rule instead.  Simple POSIX rules like `UTC0' specify a time zone
+without daylight saving time; other rules can specify simple daylight
+saving regimes.  *Note Specifying the Time Zone with `TZ': (libc)TZ
+Variable.
+
+
+File: tar.info,  Node: Authors of get_date,  Prev: Specifying time zone rules,  Up: Date input formats
+
+7.10 Authors of `get_date'
+==========================
+
+`get_date' was originally implemented by Steven M. Bellovin
+(<smb@research.att.com>) while at the University of North Carolina at
+Chapel Hill.  The code was later tweaked by a couple of people on
+Usenet, then completely overhauled by Rich $alz (<rsalz@bbn.com>) and
+Jim Berets (<jberets@bbn.com>) in August, 1990.  Various revisions for
+the GNU system were made by David MacKenzie, Jim Meyering, Paul Eggert
+and others.
+
+   This chapter was originally produced by Franc,ois Pinard
+(<pinard@iro.umontreal.ca>) from the `getdate.y' source code, and then
+edited by K. Berry (<kb@cs.umb.edu>).
+
+
+File: tar.info,  Node: Formats,  Next: Media,  Prev: Date input formats,  Up: Top
+
+8 Controlling the Archive Format
+********************************
+
+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):
+
+gnu
+     Format used by GNU `tar' versions up to 1.13.25.  This format
+     derived from an early 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 `gnu' format are able to hold file names of unlimited
+     length.
+
+oldgnu
+     Format used by GNU `tar' of versions prior to 1.12.
+
+v7
+     Archive format, compatible with the V7 implementation of tar.  This
+     format imposes a number of limitations.  The most important of them
+     are:
+
+       1. The maximum length of a file name is limited to 99 characters.
+
+       2. The maximum length of a symbolic link is limited to 99
+          characters.
+
+       3. It is impossible to store special files (block and character
+          devices, fifos etc.)
+
+       4. Maximum value of user or group ID is limited to 2097151
+          (7777777 octal)
+
+       5. V7 archives do not contain symbolic ownership information
+          (user and group name of the file owner).
+
+     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 GNU `tar'
+     1.17 and Automake prior to 1.9.
+
+ustar
+     Archive format defined by POSIX.1-1988 specification.  It stores
+     symbolic ownership information.  It is also able to store special
+     files.  However, it imposes several restrictions as well:
+
+       1. 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.
+
+       2. The maximum length of a symbolic link name is limited to 100
+          characters.
+
+       3. Maximum size of a file the archive is able to accommodate is
+          8GB
+
+       4. Maximum value of UID/GID is 2097151.
+
+       5. Maximum number of bits in device major and minor numbers is
+          21.
+
+star
+     Format used by Jo"rg Schilling `star' implementation.  GNU `tar'
+     is able to read `star' archives but currently does not produce
+     them.
+
+posix
+     Archive format defined by 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 `ustar' archives will be able to
+     read most `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 GNU `tar'.
+
+
+   The following table summarizes the limitations of each of these
+formats:
+
+Format  UID            File Size      File Name      Devn
+-------------------------------------------------------------------- 
+gnu     1.8e19         Unlimited      Unlimited      63
+oldgnu  1.8e19         Unlimited      Unlimited      63
+v7      2097151        8GB            99             n/a
+ustar   2097151        8GB            256            21
+posix   Unlimited      Unlimited      Unlimited      Unlimited
+
+   The default format for GNU `tar' is defined at compilation time.
+You may check it by running `tar --help', and examining the last lines
+of its output.  Usually, GNU `tar' is configured to create archives in
+`gnu' format, however, future version will switch to `posix'.
+
+* Menu:
+
+* Compression::                 Using Less Space through Compression
+* Attributes::                  Handling File Attributes
+* Portability::                 Making `tar' Archives More Portable
+* cpio::                        Comparison of `tar' and `cpio'
+
+
+File: tar.info,  Node: Compression,  Next: Attributes,  Up: Formats
+
+8.1 Using Less Space through Compression
+========================================
+
+* Menu:
+
+* gzip::                        Creating and Reading Compressed Archives
+* sparse::                      Archiving Sparse Files
+
+
+File: tar.info,  Node: gzip,  Next: sparse,  Up: Compression
+
+8.1.1 Creating and Reading Compressed Archives
+----------------------------------------------
+
+GNU `tar' is able to create and read compressed archives.  It supports
+`gzip' and `bzip2' compression programs.  For backward compatibility,
+it also supports `compress' command, although we strongly recommend
+against using it, since there is a patent covering the algorithm it
+uses and you could be sued for patent infringement merely by running
+`compress'!  Besides, it is less effective than `gzip' and `bzip2'.
+
+   Creating a compressed archive is simple: you just specify a
+"compression option" along with the usual archive creation commands.
+The compression option is `-z' (`--gzip') to create a `gzip' compressed
+archive, `-j' (`--bzip2') to create a `bzip2' compressed archive, and
+`-Z' (`--compress') to use `compress' program.  For example:
+
+     $ tar cfz archive.tar.gz .
+
+   Reading compressed archive is even simpler: you don't need to specify
+any additional options as GNU `tar' recognizes its format
+automatically.  Thus, the following commands will list and extract the
+archive created in previous example:
+
+     # List the compressed archive
+     $ tar tf archive.tar.gz
+     # Extract the compressed archive
+     $ tar xf archive.tar.gz
+
+   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 GNU `tar'
+will indicate which option you should use.  For example:
+
+     $ cat archive.tar.gz | tar tf -
+     tar: Archive is compressed.  Use -z option
+     tar: Error is not recoverable: exiting now
+
+   If you see such diagnostics, just add the suggested option to the
+invocation of GNU `tar':
+
+     $ cat archive.tar.gz | tar tfz -
+
+   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 (`--update' (`-u')) them or delete
+(`--delete') members from them.  Likewise, you cannot append another
+`tar' archive to a compressed archive using `--append' (`-r')).
+Secondly, multi-volume archives cannot be compressed.
+
+   The following table summarizes compression options used by GNU `tar'.
+
+`-z'
+`--gzip'
+`--ungzip'
+     Filter the archive through `gzip'.
+
+     You can use `--gzip' and `--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 `tar' program to enforce the specified (or default) record
+     size.  The default compression parameters are used; if you need to
+     override them, set `GZIP' environment variable, e.g.:
+
+          $ GZIP=--best tar cfz archive.tar.gz subdir
+
+     Another way would be to avoid the `--gzip' (`--gunzip',
+     `--ungzip', `-z') option and run `gzip' explicitly:
+
+          $ tar cf - subdir | gzip --best -c - > archive.tar.gz
+
+     About corrupted compressed archives: `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 GNU `tar'.  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!
+
+`-j'
+`--bzip2'
+     Filter the archive through `bzip2'.  Otherwise like `--gzip'.
+
+`-Z'
+`--compress'
+`--uncompress'
+     Filter the archive through `compress'.  Otherwise like `--gzip'.
+
+     The GNU Project recommends you not use `compress', because there
+     is a patent covering the algorithm it uses.  You could be sued for
+     patent infringement merely by running `compress'.
+
+`--use-compress-program=PROG'
+     Use external compression program PROG.  Use this option if you
+     have a compression program that GNU `tar' does not support.  There
+     are two requirements to which 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 `-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.
+
+   The `--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 `gpg' (*note gpg:
+(gpg)Top.).  The following script does that:
+
+     #! /bin/sh
+     case $1 in
+     -d) gpg --decrypt - | gzip -d -c;;
+     '') gzip -c | gpg -s ;;
+     *)  echo "Unknown option $1">&2; exit 1;;
+     esac
+
+   Suppose you name it `gpgz' and save it somewhere in your `PATH'.
+Then the following command will create a compressed archive signed with
+your private key:
+
+     $ tar -cf foo.tar.gpgz --use-compress=gpgz .
+
+Likewise, the following command will list its contents:
+
+     $ tar -tf foo.tar.gpgz --use-compress=gpgz .
+
+
+File: tar.info,  Node: sparse,  Prev: gzip,  Up: Compression
+
+8.1.2 Archiving Sparse Files
+----------------------------
+
+Files in the file system occasionally have "holes".  A "hole" in a file
+is a section of the file's contents which was never written.  The
+contents of a hole 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, `tar' could create
+an archive longer than the original.  To have `tar' attempt to
+recognize the holes in a file, use `--sparse' (`-S').  When you use
+this option, then, for any file using less disk space than would be
+expected from its length, `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 `--sparse' is not needed
+on extraction) any such files have holes created wherever the
+continuous stretches of zeros were found.  Thus, if you use `--sparse',
+`tar' archives won't take more space than the original.
+
+`-S'
+`--sparse'
+     This option instructs `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.
+
+   Consider using `--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 `--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).  *Note Incremental Dumps::.
+
+   However, be aware that `--sparse' option presents a serious
+drawback.  Namely, in order to determine if the file is sparse `tar'
+has to read it before trying to archive it, so in total the file is
+read *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.
+
+   When using `POSIX' archive format, GNU `tar' is able to store sparse
+files using in three distinct ways, called "sparse formats".  A sparse
+format is identified by its "number", consisting, as usual of two
+decimal numbers, delimited by a dot.  By default, format `1.0' is used.
+If, for some reason, you wish to use an earlier format, you can select
+it using `--sparse-version' option.
+
+`--sparse-version=VERSION'
+     Select the format to store sparse files in.  Valid VERSION values
+     are: `0.0', `0.1' and `1.0'.  *Note Sparse Formats::, for a
+     detailed description of each format.
+
+   Using `--sparse-format' option implies `--sparse'.
+
+
+File: tar.info,  Node: Attributes,  Next: Portability,  Prev: Compression,  Up: Formats
+
+8.2 Handling File Attributes
+============================
+
+     _(This message will disappear, once this node revised.)_
+
+When `tar' reads files, it updates their access times.  To avoid this,
+use the `--atime-preserve[=METHOD]' option, which can either reset the
+access time retroactively or avoid changing it in the first place.
+
+   Handling of file attributes
+
+`--atime-preserve'
+`--atime-preserve=replace'
+`--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.
+
+     `--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
+     (*note Incremental Dumps::), and it can set access or data
+     modification times incorrectly if other programs access the file
+     while `tar' is running.
+
+     `--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 `tar' knows for sure it won't work, it
+     complains right away.
+
+     Currently `--atime-preserve' with no operand defaults to
+     `--atime-preserve=replace', but this is intended to change to
+     `--atime-preserve=system' when the latter is better-supported.
+
+`-m'
+`--touch'
+     Do not extract data modification time.
+
+     When this option is used, `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 `--list' (`-t').
+
+`--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 `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 `suid' or `sgid' attributes of files are easily
+     and silently lost when files are given away.
+
+     When writing an archive, `tar' writes the user ID and user name
+     separately.  If it can't find a user name (because the user ID is
+     not in `/etc/passwd'), then it does not write one.  When restoring,
+     it tries to look the name (if one was written) up in
+     `/etc/passwd'.  If it fails, then it uses the user ID stored in
+     the archive instead.
+
+`--no-same-owner'
+`-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.
+
+`--numeric-owner'
+     The `--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 _always_ saved into `tar' archives.  The
+     identifying names are added at create time when provided by the
+     system, unless `--old-archive' (`-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 `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 `tar' archive out of this directory, before
+     cleaning everything out.  Of course, we could add a lot of options
+     to GNU `tar' for fine tuning permissions and ownership.  This is
+     not the good way, I think.  GNU `tar' is already crowded with
+     options and moreover, the approach just explained gives you a
+     great deal of control already.
+
+`-p'
+`--same-permissions'
+`--preserve-permissions'
+     Extract all protection information.
+
+     This option causes `tar' to set the modes (access permissions) of
+     extracted files exactly as recorded in the archive.  If this option
+     is not used, the current `umask' setting limits the permissions on
+     extracted files.  This option is by default enabled when `tar' is
+     executed by a superuser.
+
+     This option is meaningless with `--list' (`-t').
+
+`--preserve'
+     Same as both `--same-permissions' and `--same-order'.
+
+     The `--preserve' option has no equivalent short option name.  It
+     is equivalent to `--same-permissions' plus `--same-order'.
+
+