@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 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
* 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.
+
+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.
+
+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.
+
+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}.
+
+@section How to Create Archives
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
-archive. For example, to place the files @file{foo}, @file{bar}, and
-@file{baz} into an archive named @file{my-archive}, use the following
-command:
+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
-tar --create --file=my-archive foo bar baz
+tar --create --file=afiles.tar apple angst asparagus
@end example
The order of the arguments is not important. You could also say:
@example
-tar foo --create --file=my-archive bar baz
+tar apple --create angst --file=afiles.tar asparagus
@end example
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.
-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: can't open /dev/rmt8 : No such device or address
-tar: can't open /dev/rsmt0 : I/O error
-@end example
-
-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.
-
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:
@example
-tar --create --file=my-empty-archive
+tar --create --file=empty-archive.tar
@end example
Whenever you use @samp{tar --create}, @code{tar} will erase the current
to an existing archive, you need to use a different option.
@xref{Adding to Archives} for information on how to do this.
-The names of the members of an archive are called @dfn{member names}.
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{my-archive} (as created by the first example above) are
-@file{foo}, @file{bar}, and @file{baz}. However, suppose the archive
-were created with this command instead:
+@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 --create --file=my-new-archive ./foo bar ./baz
+tar --create --file=bfiles.tar ./balloons baboon ./bodacious
@end example
-Then, the same three files would get placed in the archive (because
-@file{./} is a synonym for the current directory), but their member
-names would now be @file{./foo}, @file{bar}, and @file{./baz}.
+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}.
If you want to see the progress of tar as it writes files into the
archive, you can use the @samp{--verbose} option.
the operation of tar is more complicated. @xref{Tar and Directories},
the last section of this tutorial, for more information.
-@section Listing Archives
+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: can't open /dev/rmt8 : No such device or address
+tar: can't open /dev/rsmt0 : I/O error
+@end example
+
+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.
+
+@section How to List Archives
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{my-archive} created in the last section could be examined with the
-command @samp{tar --list --file=my-archive}. The output of tar would
+@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
-foo
-bar
-baz
+apple
+angst
+asparagus
@end example
-The archive @file{my-new-archive} would list as follows:
+The archive @file{bfiles.tar} would list as follows:
@example
-./foo
-bar
-./baz
+./baloons
+baboon
+./bodacious
@end example
-Note that, despite the identical contents of the two archives' members,
-the member names are different. (Of course, @samp{tar --list
---file=my-empty-archive} would produce no output.)
+(Of course, @samp{tar --list --file=empty-archive.tar} would produce no
+output.)
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,
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=my-archive foo} would only print
-@samp{foo}. It is essential when specifying member names to tar that
+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=my-new-archive foo} would produce no output, because there is no
-member named @file{foo}, only one named @file{./foo}. While the file
-names @file{foo} and @file{./foo} name the same file, member names are
-compared using a simplistic name comparison, in which an exact match is
-necessary.
+--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 Extracting Files from an Archive
+@section How to Extract Members from an Archive
-In order to extract files from an archive, use @samp{tar --extract}.
+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}.
+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=my-archive foo} would create a file
-@file{foo} in the current directory with the contents of the archive
-member @file{foo}. It would remove any file named @file{foo} already
-present in the directory, but it would not change the archive in any
-way.
+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=my-new-archive foo} will fail, because there is no
-member named @file{foo}. To extract the member named @file{./foo} you
-would need to specify @samp{tar --extract --file=my-new-archive ./foo}.
-To find the exact member names of the members of an archive, use
-@samp{tar --list}. @xref{Listing Archives}.
+--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 Adding Files to Existing Archives
+@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 an archive and create a new one in
-its place. Instead, use @samp{tar --add-file}. The command @samp{tar
---add-file --file=my-archive qux} would add the file @file{qux} to the
-existing archive @file{my-archive}. It is essential that the archive
-exist already in order to use @samp{tar --add-file}.
+@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 --add-file} with the
+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 --add-file}.
+@samp{tar --append}.
-@section Deleting Files from Archives
+@section How to Delete Members from Archives
-You can delete files from an archive using @samp{tar --delete}. Specify
-the name of the archive with @samp{--file}. List the member names of
-the files 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}).
+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.
-Archives stored on a tape drive cannot be deleted from.
+You cannot delete members from an archive stored on a tape.
-@section Directories
+@section How to Archive Directories
-When the names of files or member names 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,
+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.
+entire file system.
To archive the entire contents of a directory, use @samp{tar --create}
-(or @samp{tar --add-file}) as usual, and specify the name of the
+(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
--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
-.}, it will report @samp{tar: foo is the archive; not dumped}. This
-happens because the archive @file{foo} 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} 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.
+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
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):
-@node Invoking @code{tar}, Tutorial, Introduction, Top
-@chapter How To Invoke @code{tar}
+@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
+tar --create --file=/tmp/afiles.tar --verbose apple angst asparagus
+@end example
+you can type
+@example
+tar -c -f /tmp/afiles.tar -v apple angst asparagus
+@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.
+
+@chapter Invoking @code{tar}
The usual way to invoke tar is
@example
-@code{tar} @var{options}... [@var{file-names}...]
+@code{tar} @var{options}... [@var{file-or-member-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.
+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
* Option Form:: The Forms of Arguments
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
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}.
+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}.
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
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.
+option specifies the basic operation for @code{tar} to perform.
-@itemize
-@item
-Add files to an existing archive (@samp{--add-file}, @samp{--append} or
-@samp{-r})
+@table samp
+@item --help
+Print a summary of the options to @code{tar} and do nothing else
-@item
-Compare files in an archive with files in the file system
-(@samp{--compare}, @samp{--diff} or @samp{-d})
+@item --create
+@item -c
+Create a new archive
-@item
-Add archives to another archive (@samp{--add-archive}, @samp{--catenate}
-or @samp{-A})
-@c was --concatenate. -ringo
+@item --catenate
+@item --concatenate
+@item -A
+Add the contents of one or more archives to another archive
-@item
-Create a new archive (@samp{--create} or @samp{-c})
+@item --append
+@item -a
+Add files to an existing archive
-@item
-Delete files from an archive (@samp{--delete})
+@item --list
+@item -t
+List the members in an archive
-@item
-Extract files from an archive (@samp{--extract}, @samp{--get} or @samp{-x})
+@item --delete
+Delete members from an archive
+
+@item --extract
+@item --get
+@item -x
+Extract members from an archive
-@item
-List the files in an archive (@samp{--list} or @samp{-t})
+@item --compare
+@item --diff
+@item -d
+Compare members in an archive with files in the file system
-@item
+@item --update
+@item -u
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
+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.
-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.
+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.
-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.
+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}.
-@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
argument. The modern syntax---@samp{tar -c -v -b 20 -f
/dev/rmt0}---is clearer.
+@chapter Basic @code{tar} Operations
+
+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.
+
+@section Creating a New Archive
+
+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.
+
+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}.
+
+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.
+
+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}.)
+
+There are various ways of causing @code{tar} to skip over some files,
+and not archive them. @xref{Specifying Names to @code{tar}}.
+
+@section Adding to an Existing Archive
+
+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.
+
+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}.
+
+This operation cannot be performed on some tape drives, unfortunately,
+due to deficiencies in the formats thoes tape drives use.
+
+@section Combining Archives
+
+The @samp{--catenate} (or @code{--concatenate}, or @code{-A}) causes
+@code{tar} to add the contents of several archives to an existing
+archive.
+
+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}.
+
+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.
+
+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:
+
+@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
+
+(You should only type @samp{y} after you have changed the tape;
+otherwise @code{tar} will write over the volume it just finished.)
+
+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}.)
+
+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.
+
+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.)
+
+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).
+
+
+
+
+
+
+
+XXXX MIB XXXX
+
+
+
@node Wizardry, Archive Structure, Tutorial, Top
@chapter Wizardry
projects / chaz / tar / blobdiff