@c Search for comments marked with !! or <<< (or >>>)
-@c <<< CONVENTIONS: this manual refers to "ordinary files" , "directory
-files" (or "directories"), "archive files", "archive members", and
-various I/O devices (which have names and file names).>>>
-
-@c <<< it's "file name" (not filename) unless we are talking about an
-argument, ie. @var{file-name}. also, you "use" a "file-name argument"
-to "specify" a "file".>>>
-
-@c <<< @code{tar} is always lower case, in bold. >>>
-
-@c <<< it's "operations of tar", "options to tar" also, it's " @samp{tar
---foo}" or "the @samp{--foo} operation". MIB doesn't like using
-operations and options as separate concepts. I disagree --- would be a
-mess to explain otherwise
-
-@c <<< (don't forget to comment these out in final draft) -ringo
-
-@c <<< please dont' change this without sending me e-mail. some things
-@c are in progress or waiting to be edited in hardcopy. -ringo
-@c smallbook
+@smallbook
@iftex
@c finalout
@subtitle DRAFT
@c subtitle insert month here when ready
-@author Amy Gorin, Michael I. Bushnell, and Jay Fenlason
-@c <<<best to have hack read this over and see if anything is left he
-@c wrote. I don't think so. -ringo>>>>
+@author Michael I. Bushnell and Amy Gorin
@page
@vskip 0pt plus 1filll
* Concept Index:: Concept Index
@end menu
-@node Introduction, Invoking @code{tar}, Top, Top
-@chapter @code{tar}: The GNU Tape Archiver
-
-You can use @code{tar} to create an @dfn{archive}---a single file
-which contains other files' contents as well as a listing of those
-files' characteristics. You can also use @code{tar} to read, add to,
-or manipulate already existing archives. Because an archive created
-by @code{tar} is capable of preserving file information and directory
-structure, @code{tar} is ideal for performing full and incremental
-backups, as well as for transferring groups of files between disks and
-over networks.
-
-The name @code{tar} comes from the words ``Tape ARchiver'', but
-@code{tar} can actually process archives wherever they are stored; on
-tapes and disk files, for example. In addition, tar can read archives
-from standard input or write them to standard output. (This is often
-useful if redirected another program with a pipe.)
-
-@c <<< this menu will conflict with menu above in info mode. -ringo
-@menu
-* Invoking @code{tar}:: How to invoke @code{tar} and specify arguments.
-* Tutorial:: An introduction to @code{tar}.
-* Operations:: What you can use @code{tar} to do.
-* Options:: How to change the way @code{tar} behaves.
-* Problems:: Common problems with @code{tar}.
-@end menu
-
-@node Invoking @code{tar}, Tutorial, Introduction, Top
-@chapter How To Invoke @code{tar}
-
-The usual way to invoke tar is
-
-@example
-@code{tar} @var{options}... [@var{file-names}...]
-@end example
-
-All the options start with @samp{-}. The arguments which do not start
-with @samp{-} are taken to be file-name arguments. (But
-@xref{Argument Form}.) You can actually type in arguments in any
-order. In this manual the options always precede the file-name
-arguments, to make examples easier to understand.
-
-@menu
-* Option Form:: The Forms of Arguments
-* Argument Functions:: The Functions of Arguments
-* Old Syntax for Commands:: An Old, but Still Supported, Syntax
- for @code{tar} Commands
-@end menu
-
-@node Option Form, Old Syntax for Commands, Argument Functions, Invoking @code{tar}
-@section The Forms of Arguments
-
-Most options of @code{tar} have a single letter form (a single letter
-preceded by @samp{-}), and at least one mnemonic form (a word or
-abbreviation preceded by @samp{--}). The forms are absolutely
-identical in function. For example, you can use either @samp{tar -t}
-or @samp{tar --list} to list the contents of an archive. In addition,
-mnemonic names can be given unique abbreviations. For example,
-@samp{--cre} can be used in place of @samp{--create} because there is
-no other option which begins with @samp{cre}.
-
-Some options require an additional argument. Single letter options
-which require arguments use the immediately following argument. (This
-is an exception to the rule that @code{tar} arguments which are not
-options are file-name arguments.) Mnemonic options are separated from
-their arguments by an @samp{=} sign. For example, to create an an
-archive file named @file{george}, use either @samp{tar --create
---file=george} or @samp{tar --create -f george}. Both
-@samp{--file=@var{archive-name}} and @samp{-f @var{archive-name}}
-denote the option to give the archive a non-default name, which in the
-example is @samp{george}.
-
-You can mix single letter and mnemonic forms in the same command. You
-could type the above example as @samp{tar -c --file=george} or
-@samp{tar --create -f george}. However, @code{tar} operations and
-options are case sensitive. You would not type the above example as
-@samp{tar -C --file=george}, because @samp{-C} is an option that
-causes @code{tar} to change directories, not an operation that creates
-an archive. In fact, @samp{-C} requires a further argument (the name
-of the directory which to change to). In this case, tar would think
-it needs to change to a directory named @samp{--file=george}, and
-wouldn't interpret @samp{--file-george} as an option at all!
-
-@node Argument Functions, Argument Form, Invoking @code{tar}, Invoking @code{tar}
-@section The Functions of Arguments
-
-You must give exactly one option from the following list to tar. This
-option specifies the basic operation for tar to perform.
-
-@itemize
-@item
-Add files to an existing archive (@samp{--add-file}, @samp{--append} or
-@samp{-r})
-
-@item
-Compare files in an archive with files in the file system
-(@samp{--compare}, @samp{--diff} or @samp{-d})
-
-@item
-Add archives to another archive (@samp{--add-archive}, @samp{--catenate}
-or @samp{-A})
-@c was --concatenate. -ringo
-
-@item
-Create a new archive (@samp{--create} or @samp{-c})
-
-@item
-Delete files from an archive (@samp{--delete})
-
-@item
-Extract files from an archive (@samp{--extract}, @samp{--get} or @samp{-x})
-
-@item
-List the files in an archive (@samp{--list} or @samp{-t})
-
-@item
-Update an archive by appending newer versions of already stored files
-(@samp{--update} or @samp{-u})
-@end itemize
-
-@xref{Reading and Writing}, for more information about these
-operations.
-
-The remaining options to @code{tar} change details of the operation,
-such as archive format, archive name, or level of user interaction.
-You can specify more than one option.
-
-The remaining arguments are file-name arguments. For --add-file and
---create these arguments specify the names of files (which must
-already exist) to place in the archive. For the remaining operation
-types, the file-name arguments specify archive members to compare,
-delete, extract, list, or update. When naming archive members, you
-must give the exact name of the member in the archive. When naming
-files, the normal file name rules apply.
-
-If you don't use any file-name arguments, @samp{--add-file},
-@samp{--update} and @samp{--delete} will do nothing. Naturally,
-@samp{--create} will make an empty archive if given no file-name
-arguments. The other operations of @code{tar} will act on defaults.
-
-Anytime you use a file-name argument to specify a directory file,
-@code{tar} acts recursively on all the files and directories beneath
-that directory.
-
-@node Old Syntax for Commands, , Argument Form, Invoking @code{tar}
-@section An Old, but Still Supported, Syntax for @code{tar} Commands
-
-For historical reasons, GNU @code{tar} also accepts a syntax for
-commands which splits options that require additional arguments into
-two parts. That syntax is of the form:
-
-@example
-@code{tar} @var{option-letters}... [@var{option-arguments}...] [@var{file-names}...]@refill
-@end example
-
-@noindent
-where arguments to the options appear in the same order as the letters
-to which they correspond, and the operation and all the option letters
-appear as a single argument, without separating spaces.
-
-This command syntax is useful because it lets you type the single
-letter forms of the operation and options as a single argument to
-@code{tar}, without writing preceding @samp{-}s or inserting spaces
-between letters. @samp{tar cv} or @samp{tar -cv} are equivalent to
-@samp{tar -c -v}.
-
-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 @samp{tar cvbf 20 /dev/rmt0}, for example,
-@samp{20} is the argument for @samp{-b}, @samp{/dev/rmt0} is the
-argument for @samp{-f}, and @samp{-v} does not have a corresponding
-argument. The modern syntax---@samp{tar -c -v -b 20 -f
-/dev/rmt0}---is clearer.
-
-@node Tutorial, Wizardry, Invoking @code{tar}, Top
-@chapter Getting Started With @code{tar}
+@chapter Tutorial Introduction to @code{tar}
This chapter guides you through some basic examples of @code{tar}
-operations. If you already know how to use some other version of tar,
-then you probably don't need to read this chapter. In the examples,
-the lines you should type are preceded by a @samp{%}, which is a
-typical shell prompt.
+operations. If you already know how to use some other version of
+@code{tar}, then you probably don't need to read this chapter. This
+chapter omits complicated details about many of the ways @code{tar}
+works. See later chapters for full information.
@menu
* Creating Archives:: Creating Archives
* Deleting Files:: Deleting Files From an Archive
@end menu
-@node Creating Archives, Listing Archive Contents, Tutorial, Tutorial
-@section Creating Archives
+@section What @code{tar} Does
+
+The @code{tar} program is used to create and manipulate @code{tar}
+archives. An @dfn{archive} is a single file which contains within it
+the contents of many files. In addition, the archive identifies the
+names of the files, their owner, and so forth.
+
+You can use @code{tar} archives in many ways. Initially, @code{tar}
+archives were used to store files conveniently on magnetic tape. The
+name @samp{tar} comes from this use; it stands for Tape ARchiver.
+Often, @code{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 @code{tar} archives, so that all
+the files relating to a particular program (or set of related programs)
+can be transferred as a single unit.
+
+The files inside an archive are called @dfn{members}. Within this
+manual, we use the term @dfn{file} to refer only to files accessible in
+the normal ways (by @code{ls}, @code{cat}, and so forth), and the term
+@dfn{members} to refer only to the members of an archive. Similarly, a
+@dfn{file name} is the name of a file, as it resides in the filesystem,
+and a @dfn{member name} is the name of an archive member within the
+archive.
-To create a new archive, use @code{tar --create} (or @code{tar -c}).
-You can use options to specify the name and format of the archive (as
-well as other characteristics), and you can use file-name arguments to
-specify which files to put in the archive. If you don't use any
-options or file-name arguments, @code{tar} will use default values.
-@xref{Creating Example}, for more information about the
-@samp{--create} operation.
+The @code{tar} program provides the ability to create @code{tar}
+archives, as well as for various other kinds of manipulation. The term
+@dfn{extraction} is used to refer to the process of copying an archive
+member into a file in the filesystem. One might speak of extracting a
+single member. Extracting all the members of an archive is often called
+extracting the archive. Often the term @dfn{unpack} is used to refer to
+the extraction of many or all the members of an archive.
-@menu
-* Creating Example:: Creating Archives of Files
-* Subdirectory:: Creating an Archive of a Subdirectory
-@end menu
+Conventionally, @code{tar} archives are given names ending with
+@samp{.tar}. This is not necessary for @code{tar} to operate properly,
+but this manual follows the convention in order to get the reader used
+to seeing it.
-@node Creating Example, Subdirectory, Creating Archives, Creating Archives
-@subsection Creating Archives of Files
+Occasionally archive members are referred to as files. For people
+familiar with the operation of @code{tar}, this causes no difficulty.
+However, this manual consistently uses the terminology above in
+referring to files and archive members, to make it easier to learn how
+to use @code{tar}.
-This example shows you how to create an archive file in the working
-directory containing other files in the working directory. The three
-files you archive in this example are called @file{blues},
-@file{folk}, and @file{jazz}. The archive file is called
-@file{records}. While the archive in this example is written to the
-file system, it could also be written to any other device.
+@section How to Create Archives
-(If you want to follow along with this and future examples, create a
-directory called @file{practice} containing files called @file{blues},
-@file{folk} and @file{jazz}. To create the directory, type
-@samp{mkdir practice} at the system prompt. It will probably be
-easiest to create the files using a text editor, such as Emacs.)
-
-First, change into the directory containing the files you want to
-archive:
+To create a new archive, use @samp{tar --create}. You should generally
+use the @samp{--file} option to specify the name the tar archive will
+have. Then specify the names of the files you wish to place in the new
+archive. For example, to place the files @file{apple}, @file{angst},
+and @file{asparagus} into an archive named @file{afiles.tar}, use the
+following command:
@example
-% cd practice
+tar --create --file=afiles.tar apple angst asparagus
@end example
-@noindent
-@file{~/practice} is now your working directory.
-
-Then, check that the files to be archived do in fact exist in the
-working directory, and make sure there isn't already a file in the
-working directory with the archive name you intend to use. If you
-specify an archive file name that is already in use, @code{tar} will
-overwrite the old file and its contents will be lost.
-
-To list the names of files in the working directory, type:
+The order of the arguments is not important. You could also say:
@example
-% ls
+tar apple --create angst --file=afiles.tar asparagus
@end example
-The system responds:
+This order is harder to understand however. In this manual, we will
+list the arguments in a reasonable order to make the commands easier to
+understand, but you can type them in any order you wish.
-@example
-blues folk jazz
-%
-@end example
-
-@noindent
-Then,
-@itemize @bullet
-@item
-Create a new archive (@samp{tar -c} or @samp{tar --create})
-
-@item
-Explicitly name the archive file being created (@samp{-f
-@var{archive-name}} or @samp{--file=@var{archive-name}}). If you don't
-use this option @code{tar} will write the archive to the default
-storage device, which varies from system to system.
-@c <<< this syntax may change. OK now---check before printing -ringo
-
-@code{tar} interprets archive file names relative to the working
-directory. Make sure you have write access to the working directory
-before using @code{tar}.
-
-@item
-Specify which files to put into the archive (@code{tar} interprets
-file names relative to the working directory). If you don't use any
-@var{file-name} arguments, @code{tar} will archive everything in the
-working directory.
-@end itemize
+If you don't specify the names of any files to put in the archive, then
+tar will create an empty archive. So, the following command will create
+an archive with nothing in it:
-@noindent
-Type:
@example
-% tar --create --file=records blues folk jazz
+tar --create --file=empty-archive.tar
@end example
-@noindent
-If you now list the contents of the working directory (@samp{ls}), you
-will find the archive file listed as well as the files you saw
-previously.
+Whenever you use @samp{tar --create}, @code{tar} will erase the current
+contents of the file named by @samp{--file} if it exists. To add files
+to an existing archive, you need to use a different option.
+@xref{Adding to Archives} for information on how to do this.
-@example
-% ls
-blues folk jazz records
-%
-@end example
-
-@menu
-* Listing Files:: Listing files in an archive
-* Verbose:: Using @code{tar} in Verbose Mode
-@end menu
-
-@node Listing Files, Verbose, Creating Example, Creating Example
-@subsubsection Listing files in an archive
-
-You can list the contents of an archive with another operation of
-@code{tar}---@samp{--list} or @samp{-l}. To list the contents of the
-archive you just created, type:
+When @samp{tar --create} creates an archive, the member names of the
+members of the archive are exactly the same as the file names as you
+typed them in the @code{tar} command. So, the member names of
+@file{afiles} (as created by the first example above) are @file{apple},
+@file{angst}, and @file{asparagus}. However, suppose an archive were
+created with this command:
@example
-% tar --list --file=records
+tar --create --file=bfiles.tar ./balloons baboon ./bodacious
@end example
-@noindent
-@code{tar} will respond:
-
-@example
-blues folk jazz
-@end example
+Then, the three files @file{balloons}, @file{baboon}, and
+@file{bodacious} would get placed in the archive (because @file{./} is a
+synonym for the current directory), but their member names would be
+@file{./balloons}, @file{baboon}, and @file{./bodacious}.
-@xref{Listing Archive Contents}, for a more detailed tutorial of the
-@samp{--list} operation. @xref{Listing Contents}, for more information
-about the @samp{--list} operation.
+If you want to see the progress of tar as it writes files into the
+archive, you can use the @samp{--verbose} option.
-@node Verbose, , Listing Files, Creating Example
-@subsubsection Using @code{tar} in Verbose Mode
+If one of the files named to @samp{tar --create} is a directory, then
+the operation of tar is more complicated. @xref{Tar and Directories},
+the last section of this tutorial, for more information.
-If you include the @samp{--verbose} or @samp{-v} option on the command
-line, @code{tar} will list the files it is acting on as it is working.
-In verbose mode, the creation example above would appear as:
-@cindex Verbose mode example
-@findex -v (verbose mode example)
+If you don't specify the @samp{--file} option, then @code{tar} will use
+a default. Usually this default is some physical tape drive attached to
+your machine. If there is no tape drive attached, or the default is not
+meaningful, then tar will print an error message. This error message
+might look roughly like one of the following:
@example
-% tar --create --file=records --verbose blues folk jazz
-blues
-folk
-jazz
+tar: can't open /dev/rmt8 : No such device or address
+tar: can't open /dev/rsmt0 : I/O error
@end example
-@noindent
-The first line is the command typed in by the user. The remaining
-lines are generated by @code{tar}. In the following examples we
-usually use verbose mode, though it is almost never required.
-
-@node Subdirectory, Changing, Creating Example, Creating Archives
-@subsection Creating an Archive of a Subdirectory
+If you get an error like this, mentioning a file you didn't specify
+(@file{/dev/rmt8} or @file{/dev/rsmt0} in the examples above), then @code{tar}
+is using a default value for @samp{--file}. You should generally specify a
+@samp{--file} argument whenever you use @code{tar}, rather than relying
+on a default.
-You can store a directory in an archive by using the directory name as
-a file-name argument to @code{tar}. When you specify a directory
-file, @code{tar} archives the directory file and all the files it
-contains. The names of the directory and the files it contains are
-stored in the archive relative to the current working directory---when
-the directory is extracted they will be written into the file system
-relative to the working directory at that time.
-@c <<< add an xref to --absolute-paths -ringo
+@section How to List Archives
-To archive a directory, first move to its superior directory. If you
-have been following the tutorial, you should type:
+Use @samp{tar --list} to print the names of members stored in an
+archive. Use a @samp{--file} option just as with @samp{tar --create} to
+specify the name of the archive. For example, the archive
+@file{afiles.tar} created in the last section could be examined with the
+command @samp{tar --list --file=afiles.tar}. The output of tar would
+then be:
@example
-% cd ..
-%
+apple
+angst
+asparagus
@end example
-Once in the superior directory, specify the subdirectory using a
-file-name argument. To store the directory file @file{~/practice} in
-the archive file @file{music}, type:
+The archive @file{bfiles.tar} would list as follows:
@example
-% tar --create --verbose --file=music practice
+./baloons
+baboon
+./bodacious
@end example
-@noindent
-@code{tar} should respond:
+(Of course, @samp{tar --list --file=empty-archive.tar} would produce no
+output.)
-@example
-practice/
-practice/blues
-practice/folk
-practice/jazz
-practice/records
-@end example
-
-Note that @file{~/practice/records}, another archive file, has
-itself been archived. @code{tar} will accept any file as a file to be
-archived, even an archive file.
-
-@c >>> symbolic links and changing directories are now in main body, not in
-@c >>> tutorial. -ringo
-
-@node Extracting Files
-@section Extracting Files from an Archive
-
-Creating an archive is only half the job---there would be no point in
-storing files in an archive if you couldn't retrieve them. To extract
-files from an archive, use the @samp{--extract} or @samp{-x} operation.
-
-To extract specific files, use their names as file-name arguments. If
-you use a directory name as a file-name argument, @code{tar} extracts
-all the files (including subdirectories) in that directory. If you
-don't use any file-name arguments, @code{tar} extracts all the files
-in the archive.
-
-Note: @code{tar} will extract an archive member into the file system
-without checking to see if there is already a file with the archive
-member's file name. If there is a file with that name, @code{tar}
-will @strong{overwrite} that file and its contents will be lost.
-@c <<<xref keep-old -ringo
-
-@node Extracting Specific Files, , ,
-@subsection Extracting Specific Files
-
-To extract specific files, specify them using file-name arguments.
-
-In an example above, you created the archive file
-@file{~/practice/records}, which contained the files @file{blues},
-@file{folk} and @file{jazz} in the @file{practice} directory. If, for
-some reason, you were to lose one of those text files (@samp{rm
-~/practice/blues}), you could extract it from the archive file.
-
-First, change into the @file{practice} directory. Then,
-
-@itemize @bullet
-@item
-Invoke @code{tar} and specify the @samp{--extract} operation
-(@samp{--extract}, @samp{--get} or @samp{-x})
-
-@item
-Specify the archive that the files will be extracted from
-(@samp{--file=@var{archive-name}} or @samp{-f @var{archive-name}})
-
-@item
-Specify the files to extract, using file-name arguments (if you don't
-specify any files, @code{tar} extracts all the archive members)
-@end itemize
-
-@example
-% tar --extract --file=records blues
-@end example
-
-If you list the contents of the directory, you will see that
-@file{blues} is back:
-
-@example
-% ls
-folk
-jazz
-records
-blues
-@end example
-
-@node Extracting Directories, , ,
-@subsection Extracting Directories
+If you use the @samp{--verbose} option with @samp{tar --list}, then tar
+will print out a listing reminiscent of @samp{ls -l}, showing owner,
+file size, and so forth.
-To extract a directory and all the files it contains, use the
-directory's name as a file-name argument in conjunction with @samp{tar
---extract}. Remember---@code{tar} stores and extracts file names
-relative to the working directory.
+You can also specify member names when using @samp{tar --list}. In this
+case, tar will only list the names of members you identify. For
+example, @samp{tar --list --file=afiles.tar apple} would only print
+@samp{apple}. It is essential when specifying member names to tar that
+you give the exact member names. For example, @samp{tar --list
+--file=bfiles baloons} would produce no output, because there is no
+member named @file{baloons}, only one named @file{./baloons}. While the
+file names @file{baloons} and @file{./baloons} name the same file,
+member names are compared using a simplistic name comparison, in which
+an exact match is necessary.
+
+@section How to Extract Members from an Archive
+
+In order to extract members from an archive, use @samp{tar --extract}.
+Specify the name of the archive with @samp{--file}. To extract specific
+archive members, give their member names as arguments. It essential to
+give their exact member name, as printed by @samp{tar --list}. This
+will create a copy of the archive member, with a file name the same as
+its name in the archive.
+
+Keeping the example of the two archives created at the beginning of this
+tutorial, @samp{tar --extract --file=afiles.tar apple} would create a
+file @file{apple} in the current directory with the contents of the
+archive member @file{apple}. It would remove any file named
+@file{apple} already present in the directory, but it would not change
+the archive in any way.
+
+Remember that specifying the exact member name is important. @samp{tar
+--extract --file=bfiles.tar baloons} will fail, because there is no
+member named @file{baloons}. To extract the member named
+@file{./baloons} you would need to specify @samp{tar --extract
+--file=bfiles.tar ./baloons}. To find the exact member names of the
+members of an archive, use @samp{tar --list} (@pxref{Listing
+Archives}).
+
+If you do not list any archive member names, then @samp{tar --extract}
+will extract all the members of the archive.
+
+If you give the @samp{--verbose} option, then @samp{tar --extract} will
+print the names of the archive members as it extracts them.
+
+@section How to Add Files to Existing Archives
+
+If you want to add files to an existing archive, then don't use
+@samp{tar --create}. That will erase the archive and create a new one
+in its place. Instead, use @samp{tar --append}. The command @samp{tar
+--append --file=afiles.tar arbalest} would add the file @file{arbalest}
+to the existing archive @file{afiles.tar}. The archive must already
+exist in order to use @samp{tar --append}.
+
+As with @samp{tar --create}, the member names of the newly added files
+will be the exact same as their names given on the command line. The
+@samp{--verbose} option will print out the names of the files as they
+are written into the archive.
+
+If you add a file to an archive using @samp{tar --append} with the
+same name as an archive member already present in the archive, then the
+old member is not deleted. What does happen, however, is somewhat
+complex. @xref{Multiple Members with the Same Name}. If you want to
+replace an archive member, use @samp{tar --delete} first, and then use
+@samp{tar --append}.
+
+@section How to Delete Members from Archives
+
+You can delete members from an archive using @samp{tar --delete}.
+Specify the name of the archive with @samp{--file}. List the member
+names of the members to be deleted. (If you list no member names, then
+nothing will be deleted.) The @samp{--verbose} option will cause
+@code{tar} to print the names of the members as they are deleted. As
+with @samp{tar --extract}, it is important that you give the exact
+member names when using @samp{tar --delete}. Use @samp{tar --list} to
+find out the exact member names in an archive (@pxref{Listing
+Archives}).
+
+The @samp{tar --delete} command only works with archives stored on disk.
+You cannot delete members from an archive stored on a tape.
+
+@section How to Archive Directories
+
+When the names of files or members specify directories, the operation of
+@code{tar} is more complex. Generally, when a directory is named,
+@code{tar} also operates on all the contents of the directory,
+recursively. Thus, to @code{tar}, the file name @file{/} names the
+entire file system.
+
+To archive the entire contents of a directory, use @samp{tar --create}
+(or @samp{tar --append}) as usual, and specify the name of the
+directory. For example, to archive all the contents of the current
+directory, use @samp{tar --create --file=@var{archive-name} .}. Doing
+this will give the archive members names starting with @samp{./}. To
+archive the contents of a directory named @file{foodir}, use @samp{tar
+--create --file=@var{archive-name} foodir}. In this case, the member
+names will all start with @samp{foodir/}.
+
+If you give @code{tar} a command such as @samp{tar --create
+--file=foo.tar .}, it will report @samp{tar: foo.tar is the archive; not
+dumped}. This happens because the archive @file{foo.tar} is created
+before putting any files into it. Then, when @code{tar} attempts to add
+all the files in the directory @file{.} to the archive, it notices that
+the file @file{foo.tar} is the same as the archive, and skips it. (It
+makes no sense to put an archive into itself.) GNU @code{tar} will
+continue in this case, and create the archive as normal, except for the
+exclusion of that one file. Other versions of @code{tar}, however, are
+not so clever, and will enter an infinite loop when this happens, so you
+should not depend on this behavior. In general, make sure that the
+archive is not inside a directory being dumped.
+
+When extracting files, you can also name directory archive members on
+the command line. In this case, @code{tar} extracts all the archive
+members whose names begin with the name of the directory. As usual,
+@code{tar} is not particularly clever about interpreting member names.
+The command @samp{tar --extract --file=@var{archive-name} .} will not
+extract all the contents of the archive, but only those members whose
+member names begin with @samp{./}.
+
+@section Shorthand Names
+
+Most of the options to @code{tar} come in both long forms and short
+forms. The options described in this tutorial have the following
+abbreviations (except @samp{--delete}, which has no shorthand form):
-In a previous example you stored the directory @file{~/practice} in
-the archive file @file{~/music}. If you delete the contents of
-@file{practice}, you can restore them using @code{tar}.
-
-First, change into the @file{practice} subdirectory (@samp{cd
-~/practice}). Then, remove all the files in @samp{~/practice}
-(@samp{rm *}). If you list the contents of the directory, you should
-now see that it is empty:
+@table @samp
+@item --create
+@samp{-c}
+@item --list
+@samp{-t}
+@item --extract
+@samp{-x}
+@item --append
+@samp{-r}
+@item --verbose
+@samp{-v}
+@item --file=@var{archive-name}
+@samp{-f @var{archive-name}}
+@end table
+These options make typing long @code{tar} commands easier. For example,
+instead of typing
@example
-%ls
-%
+tar --create --file=/tmp/afiles.tar --verbose apple angst asparagus
@end example
-
-@noindent Let's try to restore the contents of @file{practice} by extracting
-them from the archive file @file{~/music}:
-
+you can type
@example
-tar --extract --file=~/music practice
+tar -c -f /tmp/afiles.tar -v apple angst asparagus
@end example
-@noindent Now, list the contents of @file{practice} again:
-
-@example
-%ls
-practice
-@end example
+For more information on option syntax, @ref{Invoking @code{tar}}. In
+the remainder of this manual, short forms and long forms are given
+together when an option is discussed.
-What happened to the files? When you created @file{~/music}, your
-working directory was your home directory. When you extracted
-@file{~/music}, your working directory was @file{~/practice}.
-@code{tar} stored the files in @file{practice} relative to your home
-directory, and then extracted them relative to @file{~/practice}. The
-files are now in a new subdirectory, called
-@file{~/practice/practice}.
+@chapter Invoking @code{tar}
-To restore your files to their old positions, delete the new directory
-and its contents, and then redo the example above with your home
-directory as the working directory:
+The usual way to invoke tar is
@example
-% rm ~/practice/practice/*
-% rmdir practice
-% cd ..
-% tar --extract --file=music practice
+@code{tar} @var{options}... [@var{file-or-member-names}...]
@end example
-@noindent (@code{tar} will report that it is unable to create the
-directory @file{~/practice} because it already exists. This will not
-effect the extraction of the other archive members.)
-
-@node Listing Archive Contents, Adding to Archives, Creating Archives, Tutorial
-@section Listing the Contents of an Archive
-
-Use @samp{--list} or @samp{-t} to print the names of files stored in an
-archive. If you use file-name arguments with this operation,
-@code{tar} prints the names of the specified files if they are stored
-in the archive. If you use a directory name as a file-name argument,
-@code{tar} also prints the names of all underlying files, including
-sub-directories. If you use no file-name arguments, @code{tar} prints
-the names of all the archive members.
-
-You can use @samp{--list} with the @samp{--verbose} option to print
-archive members' attributes (owner, size, etc.).
+All the options start with @samp{-}. You can actually type in arguments
+in any order, but in this manual the options always precede the other
+arguments, to make examples easier to understand.
@menu
-* Listing names:: Listing the names of stored files
-* Additional File Info:: Getting Additional File Information
-* Specific File:: List A Specific File in an Archive
-* Listing Directories:: Listing the Contents of a Stored Directory
+* Option Form:: The Forms of Arguments
+* Argument Functions:: The Functions of Arguments
+* Old Syntax for Commands:: An Old, but Still Supported, Syntax
+ for @code{tar} Commands
@end menu
-@node Listing names, Additional File Info, Listing Archive Contents, Listing Archive Contents
-@subsection Listing the names of stored files
-
-To list the names of files stored in an archive, use the @samp{--list}
-operation of @code{tar}.
-
-In a previous example, you created the archive @file{~/music}. To
-list the contents of @file{music}, while in your home directory:
-
-@itemize @bullet
-@item
-List the contents of an archive (@samp{tar -t} or @samp{tar --list})
-
-@item
-Specify the archive to be listed (@samp{-f @var{archive-name}} or
-@samp{--file=@var{archive-name}}) @refill
-@end itemize
-
-Thus:
-
-@example
-% tar --list --file=music
-practice/
-practice/blues
-practice/folk
-practice/jazz
-practice/records
-@end example
-
-@node Additional File Info, Specific File, Listing names, Listing Archive Contents
-@subsection Listing Additional File Information
-
-To get more information when you list the names of files stored in an
-archive, specify the @samp{--verbose} option in conjunction with
-@samp{tar --list}. @code{tar} will print archive member's file
-protection, owner and group ID, size, and date and time of creation.
-
-For example:
-
-@example
-% tar --list --verbose --file=music
-drwxrwxrwx myself/user 0 May 31 21:49 1990 practice/
--rw-rw-rw- myself/user 42 May 21 13:29 1990 practice/blues
--rw-rw-rw- myself/user 62 May 23 10:55 1990 practice/folk
--rw-rw-rw- myself/user 40 May 21 13:30 1990 practice/jazz
--rw-rw-rw- myself/user 10240 May 31 21:49 1990 practice/records
-%
-@end example
-
-Note that when you use @samp{--verbose} with @samp{--list}, @code{tar}
-doesn't print the names of files as they are being acted on, though
-the @samp{--verbose} option will have this effect when used with all
-other operations.
-
-@node Specific File, Comparing Files, Additional File Info, Listing Archive Contents
-@subsection List A Specific File in an Archive
-
-To to see if a particular file is in an archive, use the name of the
-file in question as a file-name argument while specifying the
-@samp{--list} operation. For example, to see whether the file
-@file{folk} is in the archive file @file{music}, do the following:
-
-@itemize @bullet
-@item
-Invoke @code{tar}, and specify the @samp{--list} operation
-(@samp{--list} or @samp{-t}).
-
-@item
-Specify the archive file to be acted on (@samp{--file
-@var{archive-name}} or @samp{-f @var{archive-name}}).
-
-@item
-Specify the files to look for, by typing their names as file-name
-arguments. You have to type the file name as it appears in the
-archive (normally, as it is relative to the relative to the directory
-from which the archive was created). <<< xref absolute-paths -ringo
-@end itemize
-
-Type:
+@section The Forms of Arguments
-@example
-% tar --list --file=music practice/folk
-@end example
+Most options of @code{tar} have a single letter form (a single letter
+preceded by @samp{-}), and at least one mnemonic form (a word or
+abbreviation preceded by @samp{--}). The forms are absolutely
+identical in function. For example, you can use either @samp{tar -t}
+or @samp{tar --list} to list the contents of an archive. In addition,
+mnemonic names can be given unique abbreviations. For example,
+@samp{--cre} can be used in place of @samp{--create} because there is
+no other option which begins with @samp{cre}.
-@noindent
-@code{tar} responds:
+Some options require an additional argument. Single letter options
+which require arguments use the immediately following argument.
+Mnemonic options are separated from their arguments by an @samp{=}
+sign. For example, to create an an archive file named
+@file{george.tar}, use either @samp{tar --create --file=george.tar} or
+@samp{tar --create -f george.tar}. Both
+@samp{--file=@var{archive-name}} and @samp{-f @var{archive-name}} denote
+the option to give the archive a non-default name, which in the example
+is @file{george.tar}.
-@example
-practice/folk
-@end example
+You can mix single letter and mnemonic forms in the same command. You
+could type the above example as @samp{tar -c --file=george} or
+@samp{tar --create -f george}. However, @code{tar} operations and
+options are case sensitive. You would not type the above example as
+@samp{tar -C --file=george}, because @samp{-C} is an option that
+causes @code{tar} to change directories, not an operation that creates
+an archive. In fact, @samp{-C} requires a further argument (the name
+of the directory which to change to). In this case, tar would think
+it needs to change to a directory named @samp{--file=george}, and
+wouldn't interpret @samp{--file-george} as an option at all!
-@noindent
-If the file were not stored in the archive (for example, the file
-@file{practice/rock}), the example above would look like:
+@section The Functions of Arguments
-@example
-% tar --list --file=music practice/rock
-tar: practice/rock not found in archive
-@end example
+You must give exactly one option from the following list to tar. This
+option specifies the basic operation for @code{tar} to perform.
-@noindent
-If you had used @samp{--verbose} mode, the example above would look
-like:
+@table samp
+@item --help
+Print a summary of the options to @code{tar} and do nothing else
-@example
-% tar --list --file=music practice/folk
--rw-rw-rw- myself/user 62 May 23 10:55 1990 practice/folk
-@end example
+@item --create
+@item -c
+Create a new archive
-@node Listing Directories, , ,
-@subsection Listing the Contents of a Stored Directory
+@item --catenate
+@item --concatenate
+@item -A
+Add the contents of one or more archives to another archive
-To get information about the contents of an archived directory, use
-the directory name as a file-name argument in conjunction with
-@samp{--list}. To find out file attributes, include the
-@samp{--verbose} option.
+@item --append
+@item -a
+Add files to an existing archive
-For example, to find out about files in the directory @file{practice},
-in the archive file @file{music}, type:
+@item --list
+@item -t
+List the members in an archive
-@example
-% tar --list --file=music practice
-@end example
+@item --delete
+Delete members from an archive
-@noindent @code{tar} responds:
+@item --extract
+@item --get
+@item -x
+Extract members from an archive
-@example
-drwxrwxrwx myself/user 0 May 31 21:49 1990 practice/
--rw-rw-rw- myself/user 42 May 21 13:29 1990 practice/blues
--rw-rw-rw- myself/user 62 May 23 10:55 1990 practice/folk
--rw-rw-rw- myself/user 40 May 21 13:30 1990 practice/jazz
--rw-rw-rw- myself/user 10240 May 31 21:49 1990 practice/records
-@end example
+@item --compare
+@item --diff
+@item -d
+Compare members in an archive with files in the file system
-When you use a directory name as a file-name argument, @code{tar} acts
-on all the files (including sub-directories) in that directory.
-
-@node Comparing Files, , ,
-@section Comparing Files in an Archive with Files in the File System
-
-To compare the attributes of archive members with the attributes of
-their counterparts in the file system, use the @samp{--compare},
-@samp{--diff}, or @samp{-d}) operation. While you could use
-@samp{--list --verbose} to manually compare some file attributes, it is
-simpler to have @code{tar} itself compare file attributes and report
-back on file differences.
-@c <<<"manually"? suggestions? -ringo
-
-The @samp{--compare} operation, as its name implies, compares archive
-members with files of the same name in the file system, and reports
-back differences in file size, mode, owner and modification date.
-@samp{tar --compare} acts only on archive members---it ignores files in
-the file system that are not stored in the archive. If you give
-@samp{tar --compare} a file-name argument that does not correspond to
-the name of an archive member, @code{tar} responds with an error
-message.
-
-To compare archive members in the archive file @file{records} with
-files in the @file{~/practice} directory, first change into the
-@file{practice} directory. Then:
-
-@itemize @bullet
-@item
-Invoke @code{tar} and specify the @samp{--compare} operation.
-(@samp{--compare}, @samp{--diff}, or @samp{-d}).
-
-@item
-Specify the archive where the files to be compared are stored
-(@samp{--file=@var{archive-name}} or @samp{-f @var{archive-name}})
-
-@item
-Specify the archive members to be compared. (In this example you are
-comparing all the archive members in the archive. Since this is the
-default, you don't need to use any file-name arguments).
+@item --update
+@item -u
+Update an archive by appending newer versions of already stored files
@end itemize
-@example
-% tar --compare --file=records
-%
-@end example
-
-@noindent
-While it looks like nothing has happened, @code{tar} has, in fact,
-done the comparison---and found nothing to report.
-
-Use the @samp{--verbose} option to list the names of archive members as
-they are being compared with their counterparts of the same name in
-the file system:
-
-@example
-% tar --compare --verbose --file=records
-blues
-folk
-jazz
-%
-@end example
-
-@noindent
-If @code{tar} had had anything to report, it would have done so as it
-was comparing each file.
-
-If you remove the file @file{jazz} from the file system (@samp{rm
-jazz}), and modify the file @file{blues} (for instance, by adding text
-to it with an editor such as Emacs), the above example would look
-like:
-
-@example
-% tar --compare --verbose --file=records
-blues
-blues: mod time differs
-blues: size differs
-folk
-jazz
-jazz: does not exist
-%
-@end example
-
-Note again that while @samp{tar --compare} reports the names of archive
-members that do not have counterparts in the file system, @samp{tar
---compare} ignores files in the file system that do not have
-counterparts in the archive. To demonstrate this, create a file in
-the @file{practice} directory called @file{rock} (using any text
-editor). The new file appears when you list the directory's contents:
-
-@example
-% ls
-blues folk records rock
-@end example
-
-@noindent
-If you type the @samp{--compare} example again, @code{tar} prints the
-following:
-
-@example
-% tar --compare --verbose --file=records
-blues
-blues: mod time differs
-blues: size differs
-folk
-jazz
-jazz: does not exist
-%
-@end example
-
-@noindent
-@code{tar} ignores the file @file{rock} because @code{tar} is
-comparing archive members to files in the file system, not vice versa.
-
-If you specify @file{rock} explicitly (using a file-name argument),
-@code{tar} prints an error message:
+The remaining options to @code{tar} change details of the operation,
+such as archive format, archive name, or level of user interaction.
+You can specify more than one option.
-@example
-% tar --compare --verbose --file=records rock
-tar: rock not found in archive
-%
-@end example
+The remaining arguments are interpreted either as file names or as
+member names, depending on the basic operation @code{tar} is
+performing. For @samp{--append} and @samp{--create} these arguments
+specify the names of files (which must already exist) to place in the
+archive. For the remaining operation types, the additional arguments
+specify archive members to compare, delete, extract, list, or update.
+When naming archive members, you must give the exact name of the member
+in the archive, as it is printed by @code{tar --list}. When naming
+files, the normal file name rules apply.
-@menu
-* Comparing Directories:: Using Compare on Directories
-@end menu
+If you don't use any additional arguments, @samp{--append},
+@samp{--catenate}, and @samp{--delete} will do nothing. Naturally,
+@samp{--create} will make an empty archive if given no files to add.
+The other operations of @code{tar} (@samp{--list}, @samp{--extract},
+@samp{--compare}, and @samp{--update}) will act on the entire contents
+of the archive.
-@node Comparing Directories, , ,
-@subsubsection Using Compare on Directories
+If you give the name of a directory as either a file name or a member
+name, then @code{tar} acts recursively on all the files and directories
+beneath that directory. For example, the name @file{/} identifies all
+the files in the filesystem to @code{tar}.
-In addition to using @samp{--compare} to compare text files, you can
-use @samp{--compare} to compare directories. To illustrate this,
-re-create the examples above using your home directory as the working
-directory, and using the archive file @file{~/music} instead of the
-archive file @file{~/practice/records}.
+@section An Old, but Still Supported, Syntax for @code{tar} Commands
-First, change into your home directory (@samp{cd ~}). Then, try the
-above example using @file{music} as the specified archive file, and
-@file{practice} as a file-name argument.
+For historical reasons, GNU @code{tar} also accepts a syntax for
+commands which splits options that require additional arguments into
+two parts. That syntax is of the form:
@example
-% tar --compare --verbose --file=music practice
+@code{tar} @var{option-letters}... [@var{option-arguments}...] [@var{file-names}...]@refill
@end example
@noindent
-If you have been following along with the tutorial, @code{tar} will
-respond:
-
-@example
-practice
-practice/blues
-practice/blues: mod time differs
-practice/blues: size differs
-practice/folk
-practice/jazz
-practice/jazz: does not exist
-practice/records
-@end example
+where arguments to the options appear in the same order as the letters
+to which they correspond, and the operation and all the option letters
+appear as a single argument, without separating spaces.
-@node Adding to Archives, Concatenate, Listing Archive Contents, Tutorial
-@section Adding Files to Existing Archives
+This command syntax is useful because it lets you type the single
+letter forms of the operation and options as a single argument to
+@code{tar}, without writing preceding @samp{-}s or inserting spaces
+between letters. @samp{tar cv} or @samp{tar -cv} are equivalent to
+@samp{tar -c -v}.
-@c >>> we want people to use the script for backups, so I an not going to
-@c >>> use backups as an explanation in the tutorial. (people can still
-@c >>> do it if they really want to) -ringo
+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 @samp{tar cvbf 20 /dev/rmt0}, for example,
+@samp{20} is the argument for @samp{-b}, @samp{/dev/rmt0} is the
+argument for @samp{-f}, and @samp{-v} does not have a corresponding
+argument. The modern syntax---@samp{tar -c -v -b 20 -f
+/dev/rmt0}---is clearer.
-While you can use @code{tar} to create a new archive every time you
-want to store a file, it is more sometimes efficient to add files to
-an existing archive.
+@chapter Basic @code{tar} Operations
-To add new files to an existing archive, use the @samp{--add-file},
-@samp{--append} or @samp{-r} operation. To add newer versions of
-archive members to an archive, use the @samp{--update} or @samp{-u}
-operation.
+This chapter describes the basic operations supported by the @code{tar}
+program. A given invocation of @code{tar} will do exactly one of these
+operations.
-@menu
-* Append:: Appending Files to an Archive
-* Update:: Updating Files in an Archive
-@end menu
+@section Creating a New Archive
-@node Append, Update, Adding to Archives, Adding to Archives
-@subsection Appending Files to an Archive
-
-The simplest method of adding a file to an existing archive is the
-@samp{--add-file}, @samp{-r} or @samp{--append} operation, which writes
-files into the archive without regard to whether or not they are
-already archive members. When you use @samp{--add-file} you must use
-file-name arguments; there is no default. If you specify a file that
-is already stored in the archive, @code{tar} adds another copy of the
-file to the archive.
-
-If you have been following the previous examples, you should have a
-text file called @file{~/practice/rock} which has not been stored in
-either the archive file @file{~/practice/records}, or the archive file
-@file{~/music}. To add @file{rock} to @file{records}, first make
-@file{practice} the working directory (@samp{cd practice}). Then:
-
-@itemize @bullet
-@item
-Invoke @code{tar} and specify the @samp{--add-file} operation
-(@samp{--add-file}, @samp{-r} or @samp{--append})
-
-@item
-Specify the archive to which the file will be added
-(@samp{--file=@var{archive-name}} or @samp{-f @var{archive-name}})
-
-@item
-Specify the files to be added to the archive, using file-name
-arguments
-@end itemize
+The @samp{--create} (@code{-c}) option causes @code{tar} to create a new
+archive. The files to be archived are then named on the command line.
+Each file will be added to the archive with a member name exactly the
+same as the name given on the command line. (When you give an absolute
+file name @code{tar} actually modifies it slightly, @ref{Absolute
+Paths}.) If you list no files to be archived, then an empty archive is
+created.
-@noindent
-For example:
+If there are two many files to conveniently list on the command line,
+you can list the names in a file, and @code{tar} will read that file.
+@xref{Reading Names from a File}.
-@example
-% tar --add-file --file=records rock
-@end example
+If you name a directory, then @code{tar} will archive not only the
+directory, but all its contents, recursively. For example, if you name
+@file{/}, then @code{tar} will archive the entire filesystem.
-@noindent
-If you list the archive members in @file{records}, you will see that
-@file{rock} has been added to the archive:
+Do not use the option to add files to an existing archive; it will
+delete the archive and write a new one. Use @samp{--append} instead.
+(@xref{Adding to an Existing Archive}.)
-@example
-% tar --list --file=records
-blues
-folk
-jazz
-rock
-@end example
+There are various ways of causing @code{tar} to skip over some files,
+and not archive them. @xref{Specifying Names to @code{tar}}.
-@c <<< this should be some kind of node.
+@section Adding to an Existing Archive
-You can use @samp{--add-file} to keep archive members current with
-active files. Because @samp{--add-file} stores a file whether or not
-there is already an archive member with the same file name, you can
-use @samp{--add-file} to add newer versions of archive members to an
-archive. When you extract the file, only the version stored last will
-wind up in the file system. Because @samp{tar --extract} extracts
-files from an archive in sequence, and overwrites files with the same
-name in the file system, if a file name appears more than once in an
-archive the last version of the file will overwrite the previous
-versions which have just been extracted.
+The @samp{--append} (@code{-r}) option will case @code{tar} to add new
+files to an existing archive. It interprets file names and member names
+in exactly the same manner as @samp{--create}. Nothing happens if you
+don't list any names.
-If you recall from the examples using @samp{--compare} above,
-@file{blues} was changed after the archive @file{records} was created.
-It is simple, however, to use @samp{--add-file} to add the new version
-of @file{blues} to @file{records}:
+This option never deletes members. If a new member is added under the
+same name as an existing member, then both will be in the archive, with
+the new member after the old one. For information on how this affects
+reading the archive, @ref{Multiple Members with the Same Name}.
-@example
-% tar --add-file --verbose --file=records blues
-blues
-@end example
+This operation cannot be performed on some tape drives, unfortunately,
+due to deficiencies in the formats thoes tape drives use.
-@noindent
-If you now list the contents of the archive, you will obtain the following:
+@section Combining Archives
-@example
-% tar --list -f records
-blues
-folk
-jazz
-rock
-blues
-@end example
+The @samp{--catenate} (or @code{--concatenate}, or @code{-A}) causes
+@code{tar} to add the contents of several archives to an existing
+archive.
-@noindent
-The newest version of @file{blues} is at the end of the archive. When
-the files in @file{records} are extracted, the newer version of
-@file{blues} (which has the same name as the older) will overwrite the
-version stored first. When @samp{tar --extract} is finished, only the
-newer version of @file{blues} is in the file system. <<<xref
-keep-old-files>>>
-
-@node Update, , Append, Adding to Archives
-@subsection Updating Files in an Archive
-
-To keep archive members up to date with their counterparts of the same
-name in the file system, use the @samp{--update} or @samp{-u}
-operation. @samp{tar --update} adds a specified file to an archive if
-no file of that name is already stored in the archive. If there is
-already an archive member with the same name, @code{tar} checks the
-modification date of the archive member, and adds the file only if its
-modification date is later. If a file is stored in the archive but no
-longer exists under the same name in the active file system,
-@code{tar} reports an error.
-
-You could use the @samp{--add-file} option to keep an archive current,
-but do so you would either have to use the @samp{--compare} and
-@samp{--list} options to determine what files needed to be re-archived
-(which could waste a lot of time), or you would have to be willing to
-add identical copies of already archived files to the archive (which
-could waste a lot of space).
-
-You must use file-name arguments with the @samp{--update}
-operation---if you don't specify any files, @code{tar} won't act on
-any files.
-
-To see the @samp{--update} option at work, create a new file,
-@file{~/practice/classical}, and modify the file
-@file{~/practice/blues} (you can use a text editor, such as Emacs, to
-do both these things). Then, with @file{practice} as your working
-directory, invoke @samp{tar --update} using the names of all the files
-in the practice directory as file-name arguments, and specifying the
-@samp{--verbose} option:
+Name the archives to be catenated on the command line. (Nothing happens
+if you don't list any.) The members, and their member names, will be
+copied verbatim from those archives. If this causes multiple members to
+have the same name, it does not delete either; all the members with the
+same name coexist. For information on how this affects reading the
+archive, @ref{Multiple Members with the Same Name}.
-@example
-% tar --update --verbose --file=records blues folk rock classical
-blues
-classical
-%
-@end example
+You must use this option to concatenate archives. If you just combine
+them with @code{cat}, the result will not be a valid @code{tar} format
+archive.
-@noindent
-Because you specified verbose mode, @code{tar} printed out the names
-of the files it acted on. If you now list the archive members of the
-archive, (@samp{tar --list --file=records}), you will see that the file
-@file{classical} and another version of the file @file{blues} have
-been added to @file{records}.
-
-Note: When you update an archive, @code{tar} does not overwrite old
-archive members when it stores newer versions of a file. This is
-because archive members appear in an archive in the order in which
-they are stored, and some archive devices do not allow writing in the
-middle of an archive.
-
-@node Concatenate, Extracting Files Example, Adding to Archives, Tutorial
-@comment node-name, next, previous, up
-@section Concatenating Archives
-
-To concatenate archive files, use @samp{tar --concatenate} or @samp{tar
--A}. This operation adds other archives to the end of an archive.
-While it may seem intuitive to concatenate archives using @code{cat},
-the utility for adding files together, archive files which have been
-"catted" together cannot be read properly by @code{tar}. Archive
-files incorporate an end of file marker---if archives are concatenated
-using @code{cat}, this marker will appear before the end of the new
-archive. This will interfere with operations on that archive.
-@c <<<xref ignore-zeros>>>
-
-In earlier examples, you stored the @file{~/practice} directory in an
-archive file, @file{~/music}. If you have been following the
-examples, you have since changed the contents of the @file{~/practice}
-directory. There is a current version of the files in the
-@file{practice} directory, however, stored in the archive file
-@file{~/practice/records}.
-
-To store current versions of the files in @file{practice} in the
-archive file @file{music}, you can use @samp{tar --concatenate} to add
-the archive file @file{~/practice/records} to @file{music}. First,
-make sure you are in your home directory (@samp{cd ~}). Then:
-
-@itemize @bullet
-@item
-Invoke @code{tar}, and specify the @samp{--concatenate} operation
-(@samp{-A} or @samp{--concatenate})
-
-@item
-Specify the archive file to be added to
-(@samp{--file=@var{archive-name}} or @samp{-f @var{archive-name}})
-
-@item
-Specify the archives to be added, using file-name arguments. In this
-case, the file-name arguments are, unusually, the names of archive
-files. (Remember to include the path in the archive name, if the
-archive file is not in your working directory.)
-@end itemize
+This operation cannot be performed on some tape drives, unfortunately,
+due to deficiencies in the formats thoes tape drives use.
+
+@section Removing Archive Members
+
+You can use the @samp{--delete} option to remove members from an
+archive. Name the members on the command line to be deleted. This
+option will rewrite the archive; because of this, it does not work on
+tape drives. If you list no members to be deleted, nothing happens.
+
+@section Listing Archive Members
+
+The @samp{--list} (@samp{-t}) option will list the names of members of
+the archive. Name the members to be listed on the command line (to
+modify the way these names are interpreted, @pxref{Specifying Names to
+@code{tar}}). If you name no members, then @samp{--list} will list the
+names of all the members of the archive.
+
+To see more than just the names of the members, use the @samp{--verbose}
+option to cause @code{tar} to print out a listing similar to that of
+@samp{ls -l}.
+
+@section Extracting Archive Members
+
+Use @samp{--extract} (or @samp{--get}, or @samp{-x}) to extract members
+from an archive. For each member named (or for the entire archive if no
+members are named) on the command line (or with @samp{--files-from}) the
+a file is created with the contents of the archive member. The name of
+the file is the same as the member name.
+
+Various options cause @code{tar} to extract more than just file
+contents, such as the owner, the permissions, the modification date, and
+so forth.
+
+XXX
+The @samp{--same-permissions} (or @samp{--preserve-permissions}, or
+@samp{-p}) options cause @code{tar} to cause the new file to have the
+same permissions as the original file did when it was placed in the
+archive. Without this option, the current @code{umask} is used to
+affect the permissions.
+
+When extrating, @code{tar} normally sets the modification time of the
+file to the value recorded in the archive. The
+@samp{--modification-time} option causes @code{tar} to omit doing this.
+XXX
+
+@section Updating an Archive
+
+The @samp{--update} (or @samp{-u}) option updates a @code{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 archive member is deleted (as
+with @samp{--delete}) and then the file is added to the archive (as with
+@samp{--append}). On media where the @samp{--delete} option cannot be
+performed (such as magnetic tapes), the @samp{--update} option similarly
+fails.
+
+If no archive members are named (either on the command line or via
+@samp{--files-from}), then the entire archive is processed in this
+manner.
+
+@section Comparing Archives Members with Files
+
+The @samp{--compare} (or @samp{--diff}, or @samp{-d}) option compares
+the contents of the specified archive members against the files with the
+same names, and reports its findings. If no members are named on the
+command line (or through @samp{--files-from}), then the entire archive
+is so compared.
+
+@chapter Specifying Names to @code{tar}
+
+When specifying the names of files or members to @code{tar}, it by
+default takes the names of the files from the command line. There are
+other ways, however, to specify file or member names, or to modify the
+manner in which @code{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.
+
+@section 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
+@samp{--files-from=@var{file-name-list}} (@samp{-T
+@var{file-name-list}}) option to @code{tar}. Give the name of the file
+which contains the list as the argument to @samp{--files-from}. The
+file names should be separated by newlines in the list. If you give a
+single dash as a filename for @samp{--files-from} (that is, you specify
+@samp{--files-from=-} or @samp{-T -}), then the filenames are read from
+standard input.
+
+If you want to specify names that might contain newlines, use the
+@samp{--null} option. Then, the filenames should be separated by NUL
+characters (ASCII 000) instead of newlines. In addition, the
+@samp{--null} option turns off the @samp{-C} option (@pxref{Changing
+Directory}).
+
+@section Excluding Some Files
+
+The @samp{--exclude=@var{pattern}} option will prevent any file or
+member which matches the regular expression @var{pattern} from being
+operated on. For example, if you want to create an archive with all the
+contents of @file{/tmp} except the file @file{/tmp/foo}, you can use the
+command @samp{tar --create --file=arch.tar --exclude=foo}.
+
+If there are many files you want to exclude, you can use the
+@samp{--exclude-from=@var{exclude-list}} (@samp{-X @var{exclude-list}})
+option. This works just like the
+@samp{--files-from=@var{file-name-list}} option: specify the name of a
+file as @var{exclude-list} which contains the list of patterns you want
+to exclude.
+
+@xref{Regular Expressions} for more information on the syntax and
+meaning of regular expressions.
+
+@section Operating Only on New Files
+
+The @samp{--newer=@var{date}} (@samp{--after-date=@var{date}} or
+@samp{-N @var{date}}) limits @code{tar} to only operating on files which
+have been modified after the date specified. (For more information on
+how to specify a date, @xref{Date Formats}.) A file is considered to
+have changed if the contents have been modified, or if the owner,
+permissions, and so forth, have been changed.
+
+If you only want @code{tar} make the date comparison on the basis of the
+actual contents of the file's modification, then use the
+@samp{--newer-mtime=@var{date}} option.
+
+You should never use this option for making incremental dumps. To learn
+how to use @code{tar} to make backups, @ref{Making Backups}.
+
+@section Crossing Filesystem Boundaries
+
+The @samp{--one-file-system} option causes @code{tar} to modify its
+normal behavior in archiving the contents of directories. If a file in
+a directory is not on the same filesystem as the directory itself
+(because it is a mounted filesystem in its own right), then @code{tar}
+will not archive that file, or (if it is a directory itself) anything
+beneath it.
+
+This does not necessarily limit @code{tar} to only archiving the
+contents of a single filesystem, because all files named on the command
+line (or through the @samp{--files-from} option) will always be
+archived.
+
+@chapter Changing the Names of Members when Archiving
+
+@section Changing Directory
+
+The @samp{--directory=@var{directory}} (@samp{-C @var{directory}})
+option causes @code{tar} to change its current working directory to
+@var{directory}. Unlike most options, this one is processed at the
+point it occurs within the list of files to be processed. Consider the
+following command:
+@example
+tar --create --file=foo.tar -C /etc passwd hosts -C /lib libc.a
+@end example
+
+This command will place the files @file{/etc/passwd}, @file{/etc/hosts},
+and @file{/lib/libc.a} into the archive. However, the names of the
+archive members will be exactly what they were on the command line:
+@file{passwd}, @file{hosts}, and @file{libc.a}. The @samp{--directory}
+option is frequently used to make the archive independent of the
+original name of the directory holding the files.
+
+Note that @samp{--directory} options are interpreted consecutively. If
+@samp{--directory} option specifies a relative pathname, it is
+interpreted relative to the then current directory, which might not be
+the same as the original current working directory of @code{tar}, due to
+a previous @samp{--directory} option.
+
+When using @samp{--files-from} (@pxref{Reading Names from a File}), you
+can put @samp{-C} options in the file list. Unfortunately, you cannot
+put @samp{--directory} options in the file list. (This interpretation
+can be disabled by using the @samp{--null} option.)
+
+@section Absolute Path Names
+
+When @code{tar} extracts archive members from an archive, it strips any
+leading slashes (@code{/}) from the member name. This causes absolute
+member names in the archive to be treated as relative file names. This
+allows you to have such members extracted wherever you want, instead of
+being restricted to extracting the member in the exact directory named
+in the archive. For example, if the archive member has the name
+@file{/etc/passwd}, @code{tar} will extract it as if the name were
+really @file{etc/passwd}.
+
+Other @code{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 an inferior @code{tar} program to use. Therefore,
+GNU @code{tar} also strips leading slashes from member names when
+putting members into the archive. For example, if you ask @code{tar} to
+add the file @file{/bin/ls} to an archive, it will do so, but the member
+name will be @file{bin/ls}.
+
+If you use the @samp{--absolute-paths} option, @code{tar} will do
+neither of these transformations.
+
+@section Symbolic Links
+
+Normally, when @code{tar} archives a symbolic link, it writes a record
+to the archive naming the target of the link. In that way, the
+@code{tar} archive is a faithful record of the filesystem contents.
+However, if you want @code{tar} to actually dump the contents of the
+target of the symbolic link, then use the @samp{--dereference} option.
+
+@chapter Making @code{tar} More Verbose
+
+Various options cause @code{tar} to print information as it progresses
+in its job.
+
+The @samp{--verbose} (or @samp{-v}) option causes @code{tar} to print
+the name of each archive member or file as it is processed. Since
+@samp{--list} already prints the names of the members, @samp{--verbose}
+used with @samp{--list} causes @code{tar} to print a longer listing
+(reminiscent of @samp{ls -l}) for each member.
+
+To see the progress of @code{tar} through the archive, the
+@samp{--record-number} option prints a message for each record read or
+writted. (@xref{Archive Structure}.)
+
+The @samp{--totals} option (which is only meaningful when used with
+@samp{--create}) causes @code{tar} to print the total amount written to
+the archive, after it has been fully created.
+
+The @samp{--checkpoint} option prints an occasional message as
+@code{tar} reads or writes the archive. It is designed for those who
+don't need the more detailed (and voluminous) output of
+@samp{--record-number}, but do want visual confirmation that @code{tar}
+is actually making forward progress.
+
+@chapter Input and Output
+
+@section Changing the Archive Name
+
+By default, @code{tar} uses an archive file name compiled in when
+@code{tar} was built. Usually this refers to some physical tape drive
+on the machine. Often, the installer of @code{tar} didn't set the
+default to anything meaningful at all.
+
+As a result, most uses of @code{tar} need to tell @code{tar} where to
+find (or create) the archive. The @samp{--file=@var{archive-name}} (or
+@samp{-f @var{archive-name}} option selects another file to use as the
+archive.
+
+If the archive file name includes a colon (@samp{:}), then it is assumed
+to be a file on another machine. If the archive file is
+@samp{@var{user}@@@var{host}:@var{file}}, then @var{file} is used on the
+host @var{host}. The remote host is accessed using the @code{rsh}
+program, with a username of @var{user}. If the username is omitted
+(along with the @samp{@@} sign), then your user name will be used.
+(This is the normal @code{rsh} behavior.) It is necessary for the
+remote machine, in addition to permitting your @code{rsh} access, to
+have the @code{/usr/ucb/rmt} program installed. If you need to use a
+file whose name includes a colon, then the remote tape drive behavior
+can be inhibited by using the @samp{--force-local} option.
+
+If the filename you give to @samp{--file} is a single dash (@samp{-}),
+then @code{tar} will read the archive from (or write it to) standard
+input (or standard output).
+
+@section Extracting Members to Standard Output
+
+An archive member in normally extracted into a file with the same name
+as the archive member. However, you can use the @samp{--to-stdout} to
+cause @code{tar} to write extracted archive members to standard output.
+If you extract multiple members, they appear on standard output
+concatenated, in the order they are found in the archive.
+
+@chapter Being More Careful
+
+When using @code{tar} with many options, particularly ones with
+complicated or difficult-to-predict behavior, it is possible to make
+serious mistakes. As a result, @code{tar} provides several options that
+make observing @code{tar} easier.
+
+The @samp{--verbose} option (@pxref{Making @code{tar} More Verbose})
+causes @code{tar} to print the name of each file or archive member as it
+is processed.
+
+If you use @samp{--interactive} (or {@samp--confirm}), then @code{tar}
+will ask you for confirmation before each operation. For example, when
+extracting, it will prompt you before each archive member is extracted,
+and you can select that member for extraction or pass over to the next.
+
+The @samp{--verify} option, when using @samp{--create}, causes
+@code{tar}, after having finished creating the archive, to go back over
+it and compare its contents against the files that were placed in the
+archive.
+
+The @samp{--show-omitted-dirs} option, when reading an archive (with
+@samp{--list} or @samp{--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 @samp{--exclude} option, or some other
+reason.
+
+@chapter Using Real Tape Drives
+
+Many complexities surround the use of @code{tar} on tape drives. Since
+the creation and manipulation of archives located on magnetic tape was
+the original purpose of @code{tar}, it contains many features making
+such manipulation easier.
+
+@section Blocking
+
+When writing to tapes, @code{tar} writes the contents of the archive in
+chunks known as @dfn{blocks}. To change the default blocksize, use the
+@samp{--block-size=@var{blocking-factor}} (@samp{-b
+@var{blocking-factor}) option. Each block will then be composed of
+@var{blocking-factor} records. (Each @code{tar} record is 512 bytes.
+@xref{Archive Format}.) Each file written to the archive uses at least
+one full block. As a result, using a larger block size can result in
+more wasted space for small files. On the other hand, a larger block
+size can ofter be read and written much more efficiently.
+
+Further complicating the problem is that some tape drives ignore the
+blocking entirely. For these, a larger block size can still improve
+performance (because the software layers above the tape drive still
+honor the blocking), but not as dramatically as on tape drives that
+honor blocking.
+
+Wher reading an archive, @code{tar} can usually figure out the block
+size on itself. When this is the case, and a non-standard block size
+was used when the archive was created, @code{tar} will print a message
+about a non-standard blocking factor, and then operate normally. On
+some tape devices, however, @code{tar} cannot figure out the block size
+itself. On most of those, you can specify a blocking factor (with
+@samp{--block-size) larger than the actual blocking factor, and then use
+the @samp{--read-full-blocks} option. (If you specify a blocking factor
+with @samp{--block-size} and don't use the @samp{--read-full-blocks}
+option, then @code{tar} will not attempt to figure out the blocking size
+itself.) On some devices, you must always specify the block size
+exactly with @samp{--block-size} when reading, because @code{tar} cannot
+figure it out. In any case, use @samp{--list} before doing any
+extractions to see whether @code{tar} is reading the archive correctly.
+
+If you use a blocking factor larger than 20, older @code{tar} programs
+might not be able to read the archive, so we recommend this as a limit
+to use in practice. GNU @code{tar}, however, will support arbitrarily
+large block sizes, limited only by the amount of virtual memory or the
+physical characteristics of the tape device.
+
+@section Using Multiple Tapes
+
+Often you might want to write a large archive, one larger than will fit
+on the actual tape you are using. In such a case, you can run multiple
+@code{tar} commands, but this can be inconvenient, particularly if you
+are using options like @samp{--exclude} or dumping entire filesystems.
+Therefore, @code{tar} supports multiple tapes automatically.
+
+Use @samp{--multi-volume} on the command line, and then @code{tar} will,
+when it reaches the end of the tape, prompt for another tape, and
+continue the archive. Each tape will have an independent archive, and
+can be read without needing the other. (As an exception to this, the
+file that @code{tar} was archiving when it ran out of tape will usually
+be split between the two archives; in this case you need to extract from
+the first archive, using @samp{--multi-volume}, and then put in the
+second tape when prompted, so @code{tar} can restore both halves of the
+file.)
+
+When prompting for a new tape, @code{tar} accepts any of the following
+responses:
-@example
-% cd ~
-% tar --concatenate --file=music practice/records
-@end example
+@table @samp
+@item ?
+Request @code{tar} to explain possible responses
+@item q
+Request @code{tar} to exit immediately.
+@item n @var{file-name}
+Request @code{tar} to write the next volume on the file @var{file-name}.
+@item !
+Request @code{tar} to run a subshell.
+@item y
+Request @code{tar} to begin writing the next volume.
+@end table
-If you now list the contents of the @file{music}, you see it now
-contains the archive members of @file{practice/records}:
+(You should only type @samp{y} after you have changed the tape;
+otherwise @code{tar} will write over the volume it just finished.)
-@example
-%tar --list --file=music
-blues
-folk
-jazz
-rock
-blues
-practice/blues
-practice/folk
-practice/jazz
-practice/rock
-practice/blues
-practice/classical
-@end example
+If you want more elaborate behavior than this, give @code{tar} the
+@samp{--info-script=@var{script-name}} option. The file
+@var{script-name} is expected to be a program (or shell script) to be
+run instead of the normal prompting procedure. When the program
+finishes, @code{tar} will immediately begin writing the next volume.
+(The behavior of the @samp{n} response to the normal tape-change prompt
+is not available if you use @samp{--info-script}.)
-@node Deleting Files, , , Tutorial
-@comment node-name, next, previous, up
-@section Deleting Files From an Archive
+The method @code{tar} uses to detect end of tape is not perfect, and
+fails on some operating systems or on some devices. You can use the
+@samp{--tape-length=@var{size}} (or @samp{-L @var{size}}) option if
+@code{tar} can't detect the end of the tape itself. The @var{size}
+argument should be the size of the tape.
-In some instances, you may want to remove some files from an archive
-stored on disk
+The volume number used by @code{tar} in its tape-change prompt can be
+changed; if you give the @samp{--volno-file=@var{file-name}} option,
+then @var{file-name} should contain a decimal number. That number will
+be used as the volume number of the first volume written. When
+@code{tar} is finished, it will rewrite the file with the now--current
+volume number. (This does not change the volume number written on a
+tape label; it @emph{only} affects the number used in the prompt.)
-@quotation
-@emph{Caution:} you should never delete files from an archive stored
-on tape---because of the linear nature of tape storage, doing this is
-likely to scramble the archive.
-@end quotation
+If you want @code{tar} to cycle through a series of tape drives, then
+you can use the @samp{n} response to the tape-change prompt. This is
+error prone, however, and doesn't work at all with @samp{--info-script}.
+Therefore, if you give @code{tar} multiple @samp{--file} options, then
+the specified files will be used, in sequence, as the successive volumes
+of the archive. Only when the first one in the sequence needs to be
+used again will @code{tar} prompt for a tape change (or run the info
+script).
-To remove archive members from an archive, use the @samp{--delete}
-operation. You must specify the names of files to be removed as
-file-name arguments. All versions of the named file are removed from
-the archive.
-Execution of the @samp{--delete} operation can be very slow.
-To delete all versions of the file @file{blues} from the archive
-@file{records} in the @file{practice} directory, make sure you are in
-that directory, and then:
-@itemize @bullet
-@item
-List the contents of the archive file @file{records} (see above for
-the steps involved) to insure that the file(s) you wish to delete are
-stored in the archive. (This step is optional)
-@item
-Invoke @code{tar} and specify the @samp{--delete} operation
-(@samp{--delete}).
-@item
-Specify the name of the archive file that the file(s) will be deleted
-from (@samp{--file=@var{archive-name}} or @samp{-f @var{archive-name}})
-@item
-Specify the files to be deleted, using file-name arguments.
+XXXX MIB XXXX
-@item
-List the contents of the archive file again---note that the files have
-been removed. (this step is also optional)
-@end itemize
-@example
-% tar --list --file=records
-blues
-folk
-jazz
-% tar --delete --file=records blues
-% tar --list --file=records
-folk
-jazz
-%
-@end example
@node Wizardry, Archive Structure, Tutorial, Top
@chapter Wizardry
projects / chaz / tar / blobdiff