@c Maintenance notes:
@c 1. Pay attention to @FIXME{}s and @UNREVISED{}s
@c 2. Before creating final variant:
-@c 2.1. Run `make check-options' to make sure all options are properly
+@c 2.1. Run 'make check-options' to make sure all options are properly
@c documented;
-@c 2.2. Run `make master-menu' (see comment before the master menu).
+@c 2.2. Run 'make master-menu' (see comment before the master menu).
@include rendition.texi
@include value.texi
@defcodeindex op
+@defcodeindex kw
@c Put everything in one index (arbitrarily chosen to be the concept index).
@syncodeindex fn cp
@syncodeindex ky cp
@syncodeindex pg cp
@syncodeindex vr cp
+@syncodeindex kw cp
@copying
@value{VERSION}, @value{UPDATED}), which creates and extracts files
from archives.
-Copyright @copyright{} 1992, 1994, 1995, 1996, 1997, 1999, 2000, 2001,
-2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
+Copyright @copyright{} 1992, 1994--1997, 1999--2001, 2003--2013 Free
+Software Foundation, Inc.
@quotation
Permission is granted to copy, distribute and/or modify this document
-under the terms of the GNU Free Documentation License, Version 1.1 or
-any later version published by the Free Software Foundation; with no
-Invariant Sections, with the Front-Cover Texts being ``A GNU Manual,''
-and with the Back-Cover Texts as in (a) below. A copy of the license
-is included in the section entitled "GNU Free Documentation License".
-
-(a) The FSF's Back-Cover Text is: ``You are free to copy and modify
-this GNU Manual. Buying copies from GNU Press supports the FSF in
-developing GNU and promoting software freedom.''
+under the terms of the GNU Free Documentation License, Version 1.3 or
+any later version published by the Free Software Foundation; with the
+Invariant Sections being ``GNU General Public License'', with the
+Front-Cover Texts being ``A GNU Manual'', and with the Back-Cover Texts
+as in (a) below. A copy of the license is included in the section
+entitled ``GNU Free Documentation License''.
+
+(a) The FSF's Back-Cover Text is: ``You have the freedom to
+copy and modify this GNU manual.''
@end quotation
@end copying
* Date input formats::
* Formats::
* Media::
+* Reliability and security::
Appendices
* Tar Internals::
* Genfile::
* Free Software Needs Free Documentation::
-* Copying This Manual::
+* GNU Free Documentation License::
* Index of Command Line Options::
* Index::
* help::
* defaults::
* verbose::
+* checkpoints::
+* warnings::
* interactive::
The Three Option Styles
* Pure numbers in date strings:: 19931219, 1440.
* Seconds since the Epoch:: @@1078100502.
* Specifying time zone rules:: TZ="America/New_York", TZ="UTC0".
-* Authors of get_date:: Bellovin, Eggert, Salz, Berets, et al.
+* Authors of parse_datetime:: Bellovin, Eggert, Salz, Berets, et al.
Controlling the Archive Format
* gzip:: Creating and Reading Compressed Archives
* sparse:: Archiving Sparse Files
+Creating and Reading Compressed Archives
+
+* lbzip2:: Using lbzip2 with @GNUTAR{}.
+
Making @command{tar} Archives More Portable
* Portable Names:: Portable Names
* dereference:: Symbolic Links
+* hard links:: Hard Links
* old:: Old V7 Archives
* ustar:: Ustar Archives
* gnu:: GNU and old GNU format archives.
The second chapter is a tutorial (@pxref{Tutorial}) which provides a
gentle introduction for people who are new to using @command{tar}. It is
-meant to be self contained, not requiring any reading from subsequent
+meant to be self-contained, not requiring any reading from subsequent
chapters to make sense. It moves from topic to topic in a logical,
progressive order, building on information already explained.
two frequently used options (@samp{file} and @samp{verbose}). The other
chapters do not refer to the tutorial frequently; however, if a section
discusses something which is a complex variant of a basic concept, there
-may be a cross reference to that basic concept. (The entire book,
+may be a cross-reference to that basic concept. (The entire book,
including the tutorial, assumes that the reader understands some basic
concepts of using a Unix-type operating system; @pxref{Tutorial}.)
The third chapter presents the remaining five operations, and
information about using @command{tar} options and option syntax.
-@FIXME{this sounds more like a @acronym{GNU} Project Manuals Concept [tm] more
-than the reality. should think about whether this makes sense to say
-here, or not.} The other chapters are meant to be used as a
-reference. Each chapter presents everything that needs to be said
-about a specific topic.
+The other chapters are meant to be used as a reference. Each chapter
+presents everything that needs to be said about a specific topic.
One of the chapters (@pxref{Date input formats}) exists in its
entirety in other @acronym{GNU} manuals, and is mostly self-contained.
please report them to @file{bug-tar@@gnu.org}.
When reporting a bug, please be sure to include as much detail as
-possible, in order to reproduce it. @FIXME{Be more specific, I'd
-like to make this node as detailed as 'Bug reporting' node in Emacs
-manual}.
+possible, in order to reproduce it.
+@FIXME{Be more specific, I'd like to make this node as detailed as
+'Bug reporting' node in Emacs manual.}
@node Tutorial
@chapter Tutorial Introduction to @command{tar}
file system. You should have some basic understanding of directory
structure and how files are named according to which directory they are
in. You should understand concepts such as standard output and standard
-input, what various definitions of the term ``argument'' mean, and the
-differences between relative and absolute file names. @FIXME{and what
-else?}
+input, what various definitions of the term @samp{argument} mean, and the
+differences between relative and absolute file names.
+@FIXME{and what else?}
@item
This manual assumes that you are working from your own home directory
of three forms: long (mnemonic) form, short form, and old style. Some
of the operations and options have no short or ``old'' forms; however,
the operations and options which we will cover in this tutorial have
-corresponding abbreviations. @FIXME{make sure this is still the case,
-at the end}We will indicate those abbreviations appropriately to get
-you used to seeing them. (Note that the ``old style'' option forms
-exist in @GNUTAR{} for compatibility with Unix
+corresponding abbreviations. We will indicate those abbreviations
+appropriately to get you used to seeing them. Note, that the ``old
+style'' option forms exist in @GNUTAR{} for compatibility with Unix
@command{tar}. In this book we present a full discussion of this way
of writing options and operations (@pxref{Old Options}), and we discuss
the other two styles of writing options (@xref{Long Options}, and
If you don't specify this argument, then @command{tar} will examine
the environment variable @env{TAPE}. If it is set, its value will be
used as the archive name. Otherwise, @command{tar} will use the
-default archive, determined at the compile time. Usually it is
+default archive, determined at compile time. Usually it is
standard output or some physical tape drive attached to your machine
(you can verify what the default is by running @kbd{tar
--show-defaults}, @pxref{defaults}). If there is no tape drive
@smallexample
@group
-V--------- 0/0 1536 2006-06-09 13:07 MyVolume--Volume Header--
--rw-r--r-- gray/staff 456783 2006-06-09 12:06 aspic--Continued at
-byte 32456--
--rw-r--r-- gray/staff 62373 2006-06-09 12:06 apple
-lrwxrwxrwx gray/staff 0 2006-06-09 13:01 angst -> apple
--rw-r--r-- gray/staff 35793 2006-06-09 12:06 blues
-hrw-r--r-- gray/staff 0 2006-06-09 12:06 music link to blues
+V--------- 0/0 1536 2006-06-09 13:07 MyVolume--Volume Header--
+-rw-r--r-- gray/staff 456783 2006-06-09 12:06 aspic--Continued at byte 32456--
+-rw-r--r-- gray/staff 62373 2006-06-09 12:06 apple
+lrwxrwxrwx gray/staff 0 2006-06-09 13:01 angst -> apple
+-rw-r--r-- gray/staff 35793 2006-06-09 12:06 blues
+hrw-r--r-- gray/staff 0 2006-06-09 12:06 music link to blues
@end group
@end smallexample
is now your @dfn{working directory}. (@emph{Please note}: Although
the full file name of this directory is
@file{/@var{homedir}/practice}, in our examples we will refer to
-this directory as @file{practice}; the @var{homedir} is presumed.
+this directory as @file{practice}; the @var{homedir} is presumed.)
In general, you should check that the files to be archived exist where
you think they do (in the working directory) by running @command{ls}.
@end smallexample
This example is just like the example we showed which did not use
-@option{--verbose}, except that @command{tar} generated the remaining lines
+@option{--verbose}, except that @command{tar} generated the remaining
@iftex
-(note the different font styles).
+lines (note the different font styles).
@end iftex
@ifinfo
-.
+lines.
@end ifinfo
In the rest of the examples in this chapter, we will frequently use
they will enter an infinite loop when this happens, so you should not
depend on this behavior unless you are certain you are running
@GNUTAR{}. In general, it is wise to always place the archive outside
-of the directory being dumped.
+of the directory being dumped.)
@node list
@section How to List Archives
@smallexample
$ @kbd{tar --list --verbose --file=collection.tar folk}
--rw-r--r-- myself user 62 1990-05-23 10:55 folk
+-rw-r--r-- myself/user 62 1990-05-23 10:55 folk
@end smallexample
@cindex listing member and file names
@smallexample
@group
-$ @kbd{tar cfv archive /etc/mail}
-tar: Removing leading `/' from member names
+$ @kbd{tar --create --verbose --file archive /etc/mail}
+tar: Removing leading '/' from member names
/etc/mail/
/etc/mail/sendmail.cf
/etc/mail/aliases
-$ @kbd{tar tf archive}
+$ @kbd{tar --test --file archive}
etc/mail/
etc/mail/sendmail.cf
etc/mail/aliases
@command{tar} responds:
@smallexample
-drwxrwxrwx myself user 0 1990-05-31 21:49 practice/
--rw-r--r-- myself user 42 1990-05-21 13:29 practice/blues
--rw-r--r-- myself user 62 1990-05-23 10:55 practice/folk
--rw-r--r-- myself user 40 1990-05-21 13:30 practice/jazz
--rw-r--r-- myself user 10240 1990-05-31 21:49 practice/collection.tar
+drwxrwxrwx myself/user 0 1990-05-31 21:49 practice/
+-rw-r--r-- myself/user 42 1990-05-21 13:29 practice/blues
+-rw-r--r-- myself/user 62 1990-05-23 10:55 practice/folk
+-rw-r--r-- myself/user 40 1990-05-21 13:30 practice/jazz
+-rw-r--r-- myself/user 10240 1990-05-31 21:49 practice/collection.tar
@end smallexample
When you use a directory name as a file name argument, @command{tar} acts on
@node extract
@section How to Extract Members from an Archive
-@UNREVISED
@cindex Extraction
@cindex Retrieving files from an archive
@cindex Resurrecting files from an archive
produces this:
@smallexample
--rw-r--r-- me user 28 1996-10-18 16:31 jazz
--rw-r--r-- me user 21 1996-09-23 16:44 blues
--rw-r--r-- me user 20 1996-09-23 16:44 folk
+-rw-r--r-- me/user 28 1996-10-18 16:31 jazz
+-rw-r--r-- me/user 21 1996-09-23 16:44 blues
+-rw-r--r-- me/user 20 1996-09-23 16:44 folk
@end smallexample
@node extracting files
@smallexample
$ @kbd{tar -xvvf music.tar practice/folk practice/jazz}
--rw-r--r-- me user 28 1996-10-18 16:31 practice/jazz
--rw-r--r-- me user 20 1996-09-23 16:44 practice/folk
+-rw-r--r-- me/user 28 1996-10-18 16:31 practice/jazz
+-rw-r--r-- me/user 20 1996-09-23 16:44 practice/folk
@end smallexample
@noindent
@smallexample
tar: folk: Not found in archive
tar: jazz: Not found in archive
-$
@end smallexample
@noindent
@smallexample
$ @kbd{tar -tvf music.tar}
+practice/blues
practice/folk
practice/jazz
-practice/rock
@end smallexample
@FIXME{make sure the above works when going through the examples in
@node going further
@section Going Further Ahead in this Manual
+@UNREVISED
@FIXME{need to write up a node here about the things that are going to
be in the rest of the manual.}
@node tar invocation
@chapter Invoking @GNUTAR{}
-@UNREVISED
This chapter is about how one invokes the @GNUTAR{}
command, from the command synopsis (@pxref{Synopsis}). There are
* Synopsis::
* using tar options::
* Styles::
-* All Options::
-* help::
-* defaults::
-* verbose::
-* interactive::
+* All Options:: All @command{tar} Options.
+* help:: Where to Get Help.
+* defaults:: What are the Default Values.
+* verbose:: Checking @command{tar} progress.
+* checkpoints:: Checkpoints.
+* warnings:: Controlling Warning Messages.
+* interactive:: Asking for Confirmation During Operations.
+* external:: Running External Commands.
@end menu
@node Synopsis
@option{--extract}, @option{--compare}, and @option{--update})
will act on the entire contents of the archive.
+@anchor{exit status}
@cindex exit status
@cindex return status
Besides successful exits, @GNUTAR{} may fail for
many reasons. Some reasons correspond to bad usage, that is, when the
-@command{tar} command is improperly written. Errors may be
-encountered later, while encountering an error processing the archive
-or the files. Some errors are recoverable, in which case the failure
-is delayed until @command{tar} has completed all its work. Some
-errors are such that it would not meaningful, or at least risky, to
-continue processing: @command{tar} then aborts processing immediately.
-All abnormal exits, whether immediate or delayed, should always be
-clearly diagnosed on @code{stderr}, after a line stating the nature of
-the error.
+@command{tar} command line is improperly written. Errors may be
+encountered later, while processing the archive or the files. Some
+errors are recoverable, in which case the failure is delayed until
+@command{tar} has completed all its work. Some errors are such that
+it would be not meaningful, or at least risky, to continue processing:
+@command{tar} then aborts processing immediately. All abnormal exits,
+whether immediate or delayed, should always be clearly diagnosed on
+@code{stderr}, after a line stating the nature of the error.
Possible exit codes of @GNUTAR{} are summarized in the following
table:
allow you to perform a variety of tasks. You are required to choose
one operating mode each time you employ the @command{tar} program by
specifying one, and only one operation as an argument to the
-@command{tar} command (two lists of four operations each may be found
+@command{tar} command (the corresponding options may be found
at @ref{frequent operations} and @ref{Operations}). Depending on
circumstances, you may also wish to customize how the chosen operating
mode behaves. For example, you may wish to change the way the output
different times during the history of @command{tar}. These styles will be
presented below, from the most recent to the oldest.
-Some options must take an argument. (For example, @option{--file}
-(@option{-f})) takes the name of an archive file as an argument. If
+Some options must take an argument@footnote{For example, @option{--file}
+(@option{-f}) takes the name of an archive file as an argument. If
you do not supply an archive file name, @command{tar} will use a
default, but this can be confusing; thus, we recommend that you always
-supply a specific archive file name.) Where you @emph{place} the
+supply a specific archive file name.}. Where you @emph{place} the
arguments generally depends on which style of options you choose. We
will detail specific information relevant to each option style in the
sections on the different option styles, below. The differences are
@node Long Options
@subsection Long Option Style
+@cindex long options
+@cindex options, long style
+@cindex options, GNU style
+@cindex options, mnemonic names
Each option has at least one @dfn{long} (or @dfn{mnemonic}) name starting with two
dashes in a row, e.g., @option{--list}. The long names are more clear than
their corresponding short or old names. It sometimes happens that a
gives a fairly good set of hints about what the command does, even
for those not fully acquainted with @command{tar}.
+@cindex arguments to long options
+@cindex long options with mandatory arguments
Long options which require arguments take those arguments
immediately following the option name. There are two ways of
specifying a mandatory argument. It can be separated from the
@file{archive.tar} as argument by using any of the following notations:
@option{--file=archive.tar} or @option{--file archive.tar}.
+@cindex optional arguments to long options
+@cindex long options with optional arguments
In contrast, optional arguments must always be introduced using
an equal sign. For example, the @option{--backup} option takes
an optional argument specifying backup type. It must be used
@node Short Options
@subsection Short Option Style
+@cindex short options
+@cindex options, short style
+@cindex options, traditional
Most options also have a @dfn{short option} name. Short options start with
a single dash, and are followed by a single character, e.g., @option{-t}
(which is equivalent to @option{--list}). The forms are absolutely
The short option names are faster to type than long option names.
+@cindex arguments to short options
+@cindex short options with mandatory arguments
Short options which require arguments take their arguments immediately
following the option, usually separated by white space. It is also
possible to stick the argument right after the short option name, using
@w{@option{-f @var{archive-name}}} denote the option which indicates a
specific archive, here named @file{archive.tar}.
+@cindex optional arguments to short options
+@cindex short options with optional arguments
Short options which take optional arguments take their arguments
immediately following the option letter, @emph{without any intervening
white space characters}.
@node Old Options
@subsection Old Option Style
-@UNREVISED
+@cindex options, old style
+@cindex old option style
+@cindex option syntax, traditional
-Like short options, @dfn{old options} are single letters. However, old options
+As far as we know, all @command{tar} programs, @acronym{GNU} and
+non-@acronym{GNU}, support @dfn{old options}: that is, if the first
+argument does not start with @samp{-}, it is assumed to specify option
+letters. @GNUTAR{} supports old options not only for historical
+reasons, but also because many people are used to them. If the first
+argument does not start with a dash, you are announcing the old option
+style instead of the short option style; old options are decoded
+differently.
+
+Like short options, old options are single letters. However, old options
must be written together as a single clumped set, without spaces separating
-them or dashes preceding them@footnote{Beware that if you precede options
-with a dash, you are announcing the short option style instead of the
-old option style; short options are decoded differently.}. This set
+them or dashes preceding them. This set
of letters must be the first to appear on the command line, after the
@command{tar} program name and some white space; old options cannot appear
anywhere else. The letter of an old option is exactly the same letter as
long option @option{--list}. So for example, the command @w{@samp{tar
cv}} specifies the option @option{-v} in addition to the operation @option{-c}.
+@cindex arguments to old options
+@cindex old options with mandatory arguments
When options that need arguments are given together with the command,
all the associated arguments follow, in the same order as the options.
Thus, the example given previously could also be written in the old
Here, @samp{20} is the argument of @option{-b} and @samp{/dev/rmt0} is
the argument of @option{-f}.
-On the other hand, this old style syntax makes it difficult to match
+The old style syntax can make it difficult to match
option letters with their corresponding arguments, and is often
confusing. In the command @w{@samp{tar cvbf 20 /dev/rmt0}}, for example,
@samp{20} is the argument for @option{-b}, @samp{/dev/rmt0} is the
second example, however, uses @file{z} as the value for option
@samp{f} --- probably not what was intended.
-Old options are kept for compatibility with old versions of @command{tar}.
-
This second example could be corrected in many ways, among which the
following are equivalent:
@kbd{tar cf archive.tar.gz -z file}
@end smallexample
-@cindex option syntax, traditional
-As far as we know, all @command{tar} programs, @acronym{GNU} and
-non-@acronym{GNU}, support old options. @GNUTAR{}
-supports them not only for historical reasons, but also because many
-people are used to them. For compatibility with Unix @command{tar},
-the first argument is always treated as containing command and option
-letters even if it doesn't start with @samp{-}. Thus, @samp{tar c} is
-equivalent to @w{@samp{tar -c}:} both of them specify the
-@option{--create} (@option{-c}) command to create an archive.
-
@node Mixing
@subsection Mixing Option Styles
+@cindex options, mixing different styles
All three styles may be intermixed in a single @command{tar} command,
so long as the rules for each style are fully
respected@footnote{Before @GNUTAR{} version 1.11.6,
@var{name} argument having the value @samp{archive.tar}. The last
example contains only old style option letters (repeating option
@samp{c} twice), not all of which are meaningful (eg., @samp{.},
-@samp{h}, or @samp{i}), with no argument value. @FIXME{not sure i liked
+@samp{h}, or @samp{i}), with no argument value.
+@FIXME{not sure i liked
the first sentence of this paragraph..}
@node All Options
@section All @command{tar} Options
The coming manual sections contain an alphabetical listing of all
-@command{tar} operations and options, with brief descriptions and cross
-references to more in-depth explanations in the body of the manual.
+@command{tar} operations and options, with brief descriptions and
+cross-references to more in-depth explanations in the body of the manual.
They also contain an alphabetically arranged table of the short option
forms with their corresponding long option. You can use this table as
a reference for deciphering @command{tar} commands in scripts.
@opsummary{delete}
@item --delete
-Deletes members from the archive. Don't try this on a archive on a
+Deletes members from the archive. Don't try this on an archive on a
tape! @xref{delete}.
@opsummary{diff}
@itemx -P
Normally when creating an archive, @command{tar} strips an initial
-@samp{/} from member names. This option disables that behavior.
-@xref{absolute}.
+@samp{/} from member names, and when extracting from an archive @command{tar}
+treats names specially if they have initial @samp{/} or internal
+@samp{..}. This option disables that behavior. @xref{absolute}.
@opsummary{after-date}
@item --after-date
time, as the times of their accesses will be lost. On most platforms
restoring the access time also requires @command{tar} to restore the
data modification time too, so this option may also cause problems if
-other programs are writing the file at the same time. (Tar attempts
+other programs are writing the file at the same time (@command{tar} attempts
to detect this situation, but cannot do so reliably due to race
-conditions.) Worse, on most platforms restoring the access time also
+conditions). Worse, on most platforms restoring the access time also
updates the status change time, which means that this option is
incompatible with incremental backups.
@option{--atime-preserve=replace}, but this may change in the future
as support for @option{--atime-preserve=system} improves.
-If your operating system does not support
+If your operating or file system does not support
@option{--atime-preserve=@-system}, you might be able to preserve access
-times reliably by by using the @command{mount} command. For example,
+times reliably by using the @command{mount} command. For example,
you can mount the file system read-only, or access the file system via
a read-only loopback mount, or use the @samp{noatime} mount option
available on some systems. However, mounting typically requires
@itemx -a
During a @option{--create} operation, enables automatic compressed
-format recognition based on the archive suffix. @xref{gzip}.
+format recognition based on the archive suffix. The effect of this
+option is cancelled by @option{--no-auto-compress}. @xref{gzip}.
@opsummary{backup}
@item --backup=@var{backup-type}
This option tells @command{tar} to read or write archives through
@code{bzip2}. @xref{gzip}.
+@opsummary{check-device}
+@item --check-device
+Check device numbers when creating a list of modified files for
+incremental archiving. This is the default. @xref{device numbers},
+for a detailed description.
+
@opsummary{checkpoint}
@item --checkpoint[=@var{number}]
This option directs @command{tar} to print periodic checkpoint
messages as it reads through the archive. It is intended for when you
want a visual indication that @command{tar} is still running, but
-don't want to see @option{--verbose} output. For a detailed
-description, see @ref{Progress information}.
+don't want to see @option{--verbose} output. You can also instruct
+@command{tar} to execute a list of actions on each checkpoint, see
+@option{--checkpoint-action} below. For a detailed description, see
+@ref{checkpoints}.
+
+@opsummary{checkpoint-action}
+@item --checkpoint-action=@var{action}
+Instruct @command{tar} to execute an action upon hitting a
+breakpoint. Here we give only a brief outline. @xref{checkpoints},
+for a complete description.
+
+The @var{action} argument can be one of the following:
+
+@table @asis
+@item bell
+Produce an audible bell on the console.
+
+@item dot
+@itemx .
+Print a single dot on the standard listing stream.
+
+@item echo
+Display a textual message on the standard error, with the status and
+number of the checkpoint. This is the default.
+
+@item echo=@var{string}
+Display @var{string} on the standard error. Before output, the string
+is subject to meta-character expansion.
+
+@item exec=@var{command}
+Execute the given @var{command}.
+
+@item sleep=@var{time}
+Wait for @var{time} seconds.
+
+@item ttyout=@var{string}
+Output @var{string} on the current console (@file{/dev/tty}).
+@end table
+
+Several @option{--checkpoint-action} options can be specified. The
+supplied actions will be executed in order of their appearance in the
+command line.
+
+Using @option{--checkpoint-action} without @option{--checkpoint}
+assumes default checkpoint frequency of one checkpoint per 10 records.
@opsummary{check-links}
@item --check-links
complies to UNIX98, was introduced with version
1.15.91. @xref{Changes}, for more information.}.
+@xref{hard links}.
+
@opsummary{compress}
@opsummary{uncompress}
@item --compress
@item --dereference
@itemx -h
-When creating a @command{tar} archive, @command{tar} will archive the
-file that a symbolic link points to, rather than archiving the
-symlink. @xref{dereference}.
+When reading or writing a file to be archived, @command{tar} accesses
+the file that a symbolic link points to, rather than the symlink
+itself. @xref{dereference}.
@opsummary{directory}
@item --directory=@var{dir}
When performing operations, @command{tar} will skip files that match
@var{pattern}. @xref{exclude}.
+@opsummary{exclude-backups}
+@item --exclude-backups
+Exclude backup and lock files. @xref{exclude,, exclude-backups}.
+
@opsummary{exclude-from}
@item --exclude-from=@var{file}
@itemx -X @var{file}
Exclude from dump any directory containing a valid cache directory
tag file, but still dump the directory node and the tag file itself.
-@xref{exclude}.
+@xref{exclude,, exclude-caches}.
@opsummary{exclude-caches-under}
@item --exclude-caches-under
@item --exclude-tag=@var{file}
Exclude from dump any directory containing file named @var{file}, but
-dump the directory node and @var{file} itself. @xref{exclude}.
+dump the directory node and @var{file} itself. @xref{exclude,, exclude-tag}.
@opsummary{exclude-tag-under}
@item --exclude-tag-under=@var{file}
Exclude from dump the contents of any directory containing file
-named @var{file}, but dump the directory node itself. @xref{exclude}.
+named @var{file}, but dump the directory node itself. @xref{exclude,,
+exclude-tag-under}.
@opsummary{exclude-tag-all}
@item --exclude-tag-all=@var{file}
Exclude from dump any directory containing file named @var{file}.
-@xref{exclude}.
+@xref{exclude,,exclude-tag-all}.
@opsummary{exclude-vcs}
@item --exclude-vcs
Exclude from dump directories and files, that are internal for some
widely used version control systems.
-@xref{exclude}.
+@xref{exclude,,exclude-vcs}.
@opsummary{file}
@item --file=@var{archive}
@xref{Formats}, for a detailed discussion of these formats.
+@opsummary{full-time}
+@item --full-time
+This option instructs @command{tar} to print file times to their full
+resolution. Usually this means 1-second resolution, but that depends
+on the underlying file system. The @option{--full-time} option takes
+effect only when detailed output (verbosity level 2 or higher) has
+been requested using the @option{--verbose} option, e.g., when listing
+or extracting archives:
+
+@smallexample
+$ @kbd{tar -t -v --full-time -f archive.tar}
+@end smallexample
+
+@noindent
+or, when creating an archive:
+
+@smallexample
+$ @kbd{tar -c -vv --full-time -f archive.tar .}
+@end smallexample
+
+Notice, thar when creating the archive you need to specify
+@option{--verbose} twice to get a detailed output (@pxref{verbose
+tutorial}).
+
@opsummary{group}
@item --group=@var{group}
Files added to the @command{tar} archive will have a group @acronym{ID} of @var{group},
-rather than the group from the source file. @var{group} is first decoded
-as a group symbolic name, but if this interpretation fails, it has to be
-a decimal numeric group @acronym{ID}. @xref{override}.
+rather than the group from the source file. @var{group} can specify a
+symbolic name, or a numeric @acronym{ID}, or both as
+@var{name}:@var{id}. @xref{override}.
Also see the comments for the @option{--owner=@var{user}} option.
@command{gzip}, allowing @command{tar} to directly operate on several
kinds of compressed archives transparently. @xref{gzip}.
+@opsummary{hard-dereference}
+@item --hard-dereference
+When creating an archive, dereference hard links and store the files
+they refer to, instead of creating usual hard link members.
+
+@xref{hard links}.
+
@opsummary{help}
@item --help
@itemx -?
@item --ignore-failed-read
Do not exit unsuccessfully merely because an unreadable file was encountered.
-@xref{Reading}.
+@xref{Ignore Failed Read}.
@opsummary{ignore-zeros}
@item --ignore-zeros
@opsummary{info-script}
@opsummary{new-volume-script}
-@item --info-script=@var{script-file}
-@itemx --new-volume-script=@var{script-file}
-@itemx -F @var{script-file}
+@item --info-script=@var{command}
+@itemx --new-volume-script=@var{command}
+@itemx -F @var{command}
-When @command{tar} is performing multi-tape backups, @var{script-file} is run
-at the end of each tape. If @var{script-file} exits with nonzero status,
+When @command{tar} is performing multi-tape backups, @var{command} is run
+at the end of each tape. If it exits with nonzero status,
@command{tar} fails immediately. @xref{info-script}, for a detailed
-discussion of @var{script-file}.
+discussion of this feature.
@opsummary{interactive}
@item --interactive
performing potentially destructive options, such as overwriting files.
@xref{interactive}.
+@opsummary{--keep-directory-symlink}
+@item --keep-directory-symlink
+
+This option changes the behavior of tar when it encounters a symlink
+with the same name as the directory that it is about to extract. By
+default, in this case tar would first remove the symlink and then
+proceed extracting the directory.
+
+The @option{--keep-directory-symlink} option disables this behavior
+and instructs tar to follow symlinks to directories when extracting
+from the archive.
+
+It is mainly intended to provide compatibility with the Slackware
+installation scripts.
+
@opsummary{keep-newer-files}
@item --keep-newer-files
@item --keep-old-files
@itemx -k
-Do not overwrite existing files when extracting files from an archive.
+Do not overwrite existing files when extracting files from an
+archive. Return error if such files exist. See also
+@ref{--skip-old-files}.
+
@xref{Keep Old Files}.
@opsummary{label}
@command{tar} will only operate on archives that have a label matching
the pattern specified in @var{name}. @xref{Tape Files}.
+@opsummary{level}
+@item --level=@var{n}
+Force incremental backup of level @var{n}. As of @GNUTAR version
+@value{VERSION}, the option @option{--level=0} truncates the snapshot
+file, thereby forcing the level 0 dump. Other values of @var{n} are
+effectively ignored. @xref{--level=0}, for details and examples.
+
+The use of this option is valid only in conjunction with the
+@option{--listed-incremental} option. @xref{Incremental Dumps},
+for a detailed description.
+
@opsummary{listed-incremental}
@item --listed-incremental=@var{snapshot-file}
@itemx -g @var{snapshot-file}
With other operations, informs @command{tar} that the archive is in
incremental format. @xref{Incremental Dumps}.
+@opsummary{lzip}
+@item --lzip
+
+This option tells @command{tar} to read or write archives through
+@command{lzip}. @xref{gzip}.
+
@opsummary{lzma}
@item --lzma
This option tells @command{tar} to read or write archives through
@command{lzma}. @xref{gzip}.
+@item --lzop
+
+This option tells @command{tar} to read or write archives through
+@command{lzop}. @xref{gzip}.
+
@opsummary{mode}
@item --mode=@var{permissions}
@opsummary{new-volume-script}
@item --new-volume-script
-(see --info-script)
+(see @option{--info-script})
@opsummary{newer}
@item --newer=@var{date}
An exclude pattern can match any subsequence of the name's components.
@xref{controlling pattern-matching}.
+@opsummary{no-auto-compress}
+@item --no-auto-compress
+
+Disables automatic compressed format recognition based on the archive
+suffix. @xref{--auto-compress}. @xref{gzip}.
+
+@opsummary{no-check-device}
+@item --no-check-device
+Do not check device numbers when creating a list of modified files
+for incremental archiving. @xref{device numbers}, for
+a detailed description.
+
@opsummary{no-delay-directory-restore}
@item --no-delay-directory-restore
Print warnings about subprocesses that terminated with a nonzero exit
code. @xref{Writing to an External Program}.
+@opsummary{no-null}
+@item --no-null
+
+If the @option{--null} option was given previously, this option
+cancels its effect, so that any following @option{--files-from}
+options will expect their file lists to be newline-terminated.
+
@opsummary{no-overwrite-dir}
@item --no-overwrite-dir
the permissions specified in the archive. This is the default behavior
for ordinary users.
+@opsummary{no-seek}
+@item --no-seek
+
+The archive media does not support seeks to arbitrary
+locations. Usually @command{tar} determines automatically whether
+the archive can be seeked or not. Use this option to disable this
+mechanism.
+
@opsummary{no-unquote}
@item --no-unquote
Treat all input file or member names literally, do not interpret
@item --one-file-system
Used when creating an archive. Prevents @command{tar} from recursing into
directories that are on different file systems from the current
-directory @footnote{Earlier versions of @GNUTAR{} understood @option{-l} as a
-synonym for @option{--one-file-system}. This has changed in version
-1.15.91. @xref{Changes}, for more information.}.
+directory.
+
+@opsummary{one-top-level}
+@item --one-top-level[=@var{dir}]
+Tells @command{tar} to create a new directory beneath the extraction directory
+(or the one passed to @option{-C}) and use it to guard against
+tarbombs. In the absence of @var{dir} argument, the name of the new directory
+will be equal to the base name of the archive (file name minus the
+archive suffix, if recognized). Any member names that do not begin
+with that directory name (after
+transformations from @option{--transform} and
+@option{--strip-components}) will be prefixed with it. Recognized
+file name suffixes are @samp{.tar}, and any compression suffixes
+recognizable by @xref{--auto-compress}.
@opsummary{overwrite}
@item --overwrite
Specifies that @command{tar} should use @var{user} as the owner of members
when creating archives, instead of the user associated with the source
-file. @var{user} is first decoded as a user symbolic name, but if
-this interpretation fails, it has to be a decimal numeric user @acronym{ID}.
+file. @var{user} can specify a symbolic name, or a numeric
+@acronym{ID}, or both as @var{name}:@var{id}.
@xref{override}.
This option does not affect extraction from archives.
@opsummary{pax-option}
@item --pax-option=@var{keyword-list}
-This option is meaningful only with @acronym{POSIX.1-2001} archives
-(@pxref{posix}). It modifies the way @command{tar} handles the
+This option enables creation of the archive in @acronym{POSIX.1-2001}
+format (@pxref{posix}) and modifies the way @command{tar} handles the
extended header keywords. @var{Keyword-list} is a comma-separated
list of keyword options. @xref{PAX keywords}, for a detailed
discussion.
from pipes on systems with buggy implementations. @xref{Reading}.
@opsummary{record-size}
-@item --record-size=@var{size}
+@item --record-size=@var{size}[@var{suf}]
Instructs @command{tar} to use @var{size} bytes per record when accessing the
-archive. @xref{Blocking Factor}.
+archive. The argument can be suffixed with a @dfn{size suffix}, e.g.
+@option{--record-size=10K} for 10 Kilobytes. @xref{size-suffixes},
+for a list of valid suffixes. @xref{Blocking Factor}, for a detailed
+description of this option.
@opsummary{recursion}
@item --recursion
Assume that the archive media supports seeks to arbitrary
locations. Usually @command{tar} determines automatically whether
the archive can be seeked or not. This option is intended for use
-in cases when such recognition fails.
+in cases when such recognition fails. It takes effect only if the
+archive is open for reading (e.g. with @option{--list} or
+@option{--extract} options).
@opsummary{show-defaults}
@item --show-defaults
Here is an example of what you can see using this option:
@smallexample
-$ tar --show-defaults
---format=gnu -f- -b20 --quoting-style=escape \
+$ @kbd{tar --show-defaults}
+--format=gnu -f- -b20 --quoting-style=escape
--rmt-command=/usr/libexec/rmt --rsh-command=/usr/bin/rsh
@end smallexample
+@noindent
+Notice, that this option outputs only one line. The example output
+above has been split to fit page boundaries. @xref{defaults}.
+
@opsummary{show-omitted-dirs}
@item --show-omitted-dirs
Instructs @command{tar} to mention the directories it is skipping when
operating on a @command{tar} archive. @xref{show-omitted-dirs}.
+@opsummary{show-snapshot-field-ranges}
+@item --show-snapshot-field-ranges
+
+Displays the range of values allowed by this version of @command{tar}
+for each field in the snapshot file, then exits successfully.
+@xref{Snapshot Files}.
+
@opsummary{show-transformed-names}
@opsummary{show-stored-names}
@item --show-transformed-names
member names stored in the archive, as opposed to the actual file
names. @xref{listing member and file names}.
+@opsummary{skip-old-files}
+@item --skip-old-files
+
+Do not overwrite existing files when extracting files from an
+archive. @xref{Keep Old Files}.
+
+This option differs from @option{--keep-old-files} in that it does not
+treat such files as an error, instead it just silently avoids
+overwriting them.
+
+The @option{--warning=existing-file} option can be used together with
+this option to produce warning messages about existing old files
+(@pxref{warnings}).
+
@opsummary{sparse}
@item --sparse
@itemx -S
@noindent
would extract this file to file @file{name}.
-@opsummary{suffix}, summary
+@opsummary{suffix}
@item --suffix=@var{suffix}
Alters the suffix @command{tar} uses when backing up files from the default
@samp{~}. @xref{backup}.
@opsummary{tape-length}
-@item --tape-length=@var{num}
-@itemx -L @var{num}
+@item --tape-length=@var{num}[@var{suf}]
+@itemx -L @var{num}[@var{suf}]
Specifies the length of tapes that @command{tar} is writing as being
-@w{@var{num} x 1024} bytes long. @xref{Using Multiple Tapes}.
+@w{@var{num} x 1024} bytes long. If optional @var{suf} is given, it
+specifies a multiplicative factor to be used instead of 1024. For
+example, @samp{-L2M} means 2 megabytes. @xref{size-suffixes}, for a
+list of allowed suffixes. @xref{Using Multiple Tapes}, for a detailed
+discussion of this option.
@opsummary{test-label}
@item --test-label
@xref{Data Modification Times}.
@opsummary{transform}
+@opsummary{xform}
@item --transform=@var{sed-expr}
-
+@itemx --xform=@var{sed-expr}
Transform file or member names using @command{sed} replacement expression
@var{sed-expr}. For example,
@opsummary{uncompress}
@item --uncompress
-(See @option{--compress}. @pxref{gzip})
+(See @option{--compress}, @pxref{gzip})
@opsummary{ungzip}
@item --ungzip
-(See @option{--gzip}. @pxref{gzip})
+(See @option{--gzip}, @pxref{gzip})
@opsummary{unlink-first}
@item --unlink-first
@opsummary{use-compress-program}
@item --use-compress-program=@var{prog}
+@itemx -I=@var{prog}
Instructs @command{tar} to access the archive through @var{prog}, which is
presumed to be a compression program of some sort. @xref{gzip}.
keep track of which volume of a multi-volume archive it is working in
@var{file}. @xref{volno-file}.
+@opsummary{warning}
+@item --warning=@var{keyword}
+
+Enable or disable warning messages identified by @var{keyword}. The
+messages are suppressed if @var{keyword} is prefixed with @samp{no-}.
+@xref{warnings}.
+
@opsummary{wildcards}
@item --wildcards
Use wildcards when matching member names with patterns.
@item --wildcards-match-slash
Wildcards match @samp{/}.
@xref{controlling pattern-matching}.
+
+@opsummary{xz}
+@item --xz
+@itemx -J
+Use @command{xz} for compressing or decompressing the archives. @xref{gzip}.
+
@end table
@node Short Option Summary
@item -G @tab @ref{--incremental}.
+@item -J @tab @ref{--xz}.
+
@item -K @tab @ref{--starting-file}.
@item -L @tab @ref{--tape-length}.
@item -o @tab When creating, @ref{--no-same-owner}, when extracting ---
@ref{--portability}.
-The later usage is deprecated. It is retained for compatibility with
+The latter usage is deprecated. It is retained for compatibility with
the earlier versions of @GNUTAR{}. In future releases
@option{-o} will be equivalent to @option{--no-same-owner} only.
@smallexample
tar (GNU tar) @value{VERSION}
-Copyright (C) 2006 Free Software Foundation, Inc.
-This is free software. You may redistribute copies of it under the terms
-of the GNU General Public License <http://www.gnu.org/licenses/gpl.html>.
+Copyright (C) 2013-2014 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>.
+This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.
Written by John Gilmore and Jay Fenlason.
@command{tar} packages into a single one which would be called
@code{paxutils}. So, who knows if, one of this days, the
@option{--version} would not output @w{@samp{tar (@acronym{GNU}
-paxutils) 3.2}}}.
+paxutils) 3.2}}.}.
@cindex Obtaining help
@cindex Listing all @command{tar} options
@opindex usage
If you only wish to check the spelling of an option, running @kbd{tar
--usage} may be a better choice. This will display a terse list of
-@command{tar} option without accompanying explanations.
+@command{tar} options without accompanying explanations.
The short help output is quite succinct, and you might have to get
back to the full documentation for precise points. If you are reading
@smallexample
@group
-@kbd{tar --show-defaults}
+$ @kbd{tar --show-defaults}
--format=gnu -f- -b20 --quoting-style=escape
--rmt-command=/etc/rmt --rsh-command=/usr/bin/rsh
@end group
Verbose output appears on the standard output except when an archive is
being written to the standard output, as with @samp{tar --create
---file=- --verbose} (@samp{tar cfv -}, or even @samp{tar cv}---if the
+--file=- --verbose} (@samp{tar cvf -}, or even @samp{tar cv}---if the
installer let standard output be the default archive). In that case
@command{tar} writes verbose output to the standard error stream.
@anchor{Progress information}
@cindex Progress information
-@opindex checkpoint
The @option{--checkpoint} option prints an occasional message
as @command{tar} reads or writes the archive. It is designed for
those who don't need the more detailed (and voluminous) output of
This example shows the default checkpoint message used by
@command{tar}. If you place a dot immediately after the equal
-sign, it will print a @samp{.} at each checkpoint. For example:
+sign, it will print a @samp{.} at each checkpoint@footnote{This is
+actually a shortcut for @option{--checkpoint=@var{n}
+--checkpoint-action=dot}. @xref{checkpoints, dot}.}. For example:
@smallexample
$ @kbd{tar -c --checkpoint=.1000} /var
...
@end smallexample
+The @option{--checkpoint} option provides a flexible mechanism for
+executing arbitrary actions upon hitting checkpoints, see the next
+section (@pxref{checkpoints}), for more information on it.
+
@opindex show-omitted-dirs
@anchor{show-omitted-dirs}
The @option{--show-omitted-dirs} option, when reading an archive---with
every message it would normally produce, the block number within the
archive where the message was triggered. Also, supplementary messages
are triggered when reading blocks full of NULs, or when hitting end of
-file on the archive. As of now, if the archive if properly terminated
+file on the archive. As of now, if the archive is properly terminated
with a NUL block, the reading of the file may stop before end of file
is met, so the position of end of file will not usually show when
@option{--block-number} (@option{-R}) is used. Note that @GNUTAR{}
favor of the tape where the file appears earliest (closest to the
front of the tape). @xref{backup}.
+@node checkpoints
+@section Checkpoints
+@cindex checkpoints, defined
+@opindex checkpoint
+@opindex checkpoint-action
+
+A @dfn{checkpoint} is a moment of time before writing @var{n}th record to
+the archive (a @dfn{write checkpoint}), or before reading @var{n}th record
+from the archive (a @dfn{read checkpoint}). Checkpoints allow to
+periodically execute arbitrary actions.
+
+The checkpoint facility is enabled using the following option:
+
+@table @option
+@xopindex{checkpoint, defined}
+@item --checkpoint[=@var{n}]
+Schedule checkpoints before writing or reading each @var{n}th record.
+The default value for @var{n} is 10.
+@end table
+
+A list of arbitrary @dfn{actions} can be executed at each checkpoint.
+These actions include: pausing, displaying textual messages, and
+executing arbitrary external programs. Actions are defined using
+the @option{--checkpoint-action} option.
+
+@table @option
+@xopindex{checkpoint-action, defined}
+@item --checkpoint-action=@var{action}
+Execute an @var{action} at each checkpoint.
+@end table
+
+@cindex @code{echo}, checkpoint action
+The simplest value of @var{action} is @samp{echo}. It instructs
+@command{tar} to display the default message on the standard error
+stream upon arriving at each checkpoint. The default message is (in
+@acronym{POSIX} locale) @samp{Write checkpoint @var{n}}, for write
+checkpoints, and @samp{Read checkpoint @var{n}}, for read checkpoints.
+Here, @var{n} represents ordinal number of the checkpoint.
+
+In another locales, translated versions of this message are used.
+
+This is the default action, so running:
+
+@smallexample
+$ @kbd{tar -c --checkpoint=1000 --checkpoint-action=echo} /var
+@end smallexample
+
+@noindent
+is equivalent to:
+
+@smallexample
+$ @kbd{tar -c --checkpoint=1000} /var
+@end smallexample
+
+The @samp{echo} action also allows to supply a customized message.
+You do so by placing an equals sign and the message right after it,
+e.g.:
+
+@smallexample
+--checkpoint-action="echo=Hit %s checkpoint #%u"
+@end smallexample
+
+The @samp{%s} and @samp{%u} in the above example are
+@dfn{format specifiers}. The @samp{%s} specifier is replaced with
+the @dfn{type} of the checkpoint: @samp{write} or
+@samp{read} (or a corresponding translated version in locales other
+than @acronym{POSIX}). The @samp{%u} specifier is replaced with
+the ordinal number of the checkpoint. Thus, the above example could
+produce the following output when used with the @option{--create}
+option:
+
+@smallexample
+tar: Hit write checkpoint #10
+tar: Hit write checkpoint #20
+tar: Hit write checkpoint #30
+@end smallexample
+
+The complete list of available format specifiers follows. Some of
+them can take optional arguments. These arguments, if given, are
+supplied in curly braces between the percent sign and the specifier
+letter.
+
+@table @samp
+@item %s
+Print type of the checkpoint (@samp{write} or @samp{read}).
+
+@item %u
+Print number of the checkpoint.
+
+@item %@{r,w,d@}T
+Print number of bytes transferred so far and approximate transfer
+speed. Optional arguments supply prefixes to be used before number
+of bytes read, written and deleted, correspondingly. If absent,
+they default to @samp{R}. @samp{W}, @samp{D}. Any or all of them can
+be omitted, so, that e.g. @samp{%@{@}T} means to print corresponding
+statistics without any prefixes. Any surplus arguments, if present,
+are silently ignored.
+
+@example
+$ @kbd{tar --delete -f f.tar --checkpoint-action=echo="#%u: %T" main.c}
+tar: #1: R: 0 (0B, 0B/s),W: 0 (0B, 0B/s),D: 0
+tar: #2: R: 10240 (10KiB, 19MiB/s),W: 0 (0B, 0B/s),D: 10240
+@end example
+
+@noindent
+See also the @samp{totals} action, described below.
+
+@item %@{@var{fmt}@}t
+Output current local time using @var{fmt} as format for @command{strftime}
+(@pxref{strftime, strftime,,strftime(3), strftime(3) man page}). The
+@samp{@{@var{fmt}@}} part is optional. If not present, the default
+format is @samp{%c}, i.e. the preferred date and time representation
+for the current locale.
+
+@item %@{@var{n}@}*
+Pad output with spaces to the @var{n}th column. If the
+@samp{@{@var{n}@}} part is omitted, the current screen width
+is assumed.
+
+@item %@var{c}
+This is a shortcut for @samp{%@{%Y-%m-%d %H:%M:%S@}t: %ds, %@{read,wrote@}T%*\r},
+intended mainly for use with @samp{ttyout} action (see below).
+@end table
+
+Aside from format expansion, the message string is subject to
+@dfn{unquoting}, during which the backslash @dfn{escape sequences} are
+replaced with their corresponding @acronym{ASCII} characters
+(@pxref{escape sequences}). E.g. the following action will produce an
+audible bell and the message described above at each checkpoint:
+
+@smallexample
+--checkpoint-action='echo=\aHit %s checkpoint #%u'
+@end smallexample
+
+@cindex @code{bell}, checkpoint action
+There is also a special action which produces an audible signal:
+@samp{bell}. It is not equivalent to @samp{echo='\a'}, because
+@samp{bell} sends the bell directly to the console (@file{/dev/tty}),
+whereas @samp{echo='\a'} sends it to the standard error.
+
+@cindex @code{ttyout}, checkpoint action
+The @samp{ttyout=@var{string}} action outputs @var{string} to
+@file{/dev/tty}, so it can be used even if the standard output is
+redirected elsewhere. The @var{string} is subject to the same
+modifications as with @samp{echo} action. In contrast to the latter,
+@samp{ttyout} does not prepend @command{tar} executable name to the
+string, nor does it output a newline after it. For example, the
+following action will print the checkpoint message at the same screen
+line, overwriting any previous message:
+
+@smallexample
+--checkpoint-action="ttyout=Hit %s checkpoint #%u%*\r"
+@end smallexample
+
+@noindent
+Notice the use of @samp{%*} specifier to clear out any eventual
+remains of the prior output line. As as more complex example,
+consider this:
+
+@smallexample
+--checkpoint-action=ttyout='%@{%Y-%m-%d %H:%M:%S@}t (%d sec): #%u, %T%*\r'
+@end smallexample
+
+@noindent
+This prints the current local time, number of seconds expired since
+tar was started, the checkpoint ordinal number, transferred bytes and
+average computed I/O speed.
+
+@cindex @code{dot}, checkpoint action
+Another available checkpoint action is @samp{dot} (or @samp{.}). It
+instructs @command{tar} to print a single dot on the standard listing
+stream, e.g.:
+
+@smallexample
+$ @kbd{tar -c --checkpoint=1000 --checkpoint-action=dot} /var
+...
+@end smallexample
+
+For compatibility with previous @GNUTAR{} versions, this action can
+be abbreviated by placing a dot in front of the checkpoint frequency,
+as shown in the previous section.
+
+@cindex @code{totals}, checkpoint action
+The @samp{totals} action prints the total number of bytes transferred
+so far. The format of the data is the same as for the
+@option{--totals} option (@pxref{totals}). See also @samp{%T} format
+specifier of the @samp{echo} or @samp{ttyout} action.
+
+@cindex @code{sleep}, checkpoint action
+Yet another action, @samp{sleep}, pauses @command{tar} for a specified
+amount of seconds. The following example will stop for 30 seconds at each
+checkpoint:
+
+@smallexample
+$ @kbd{tar -c --checkpoint=1000 --checkpoint-action=sleep=30}
+@end smallexample
+
+@anchor{checkpoint exec}
+@cindex @code{exec}, checkpoint action
+Finally, the @code{exec} action executes a given external command.
+For example:
+
+@smallexample
+$ @kbd{tar -c --checkpoint=1000 --checkpoint-action=exec=/sbin/cpoint}
+@end smallexample
+
+The supplied command can be any valid command invocation, with or
+without additional command line arguments. If it does contain
+arguments, don't forget to quote it to prevent it from being split by
+the shell. @xref{external, Running External Commands}, for more detail.
+
+The command gets a copy of @command{tar}'s environment plus the
+following variables:
+
+@table @env
+@vrindex TAR_VERSION, checkpoint script environment
+@item TAR_VERSION
+@GNUTAR{} version number.
+
+@vrindex TAR_ARCHIVE, checkpoint script environment
+@item TAR_ARCHIVE
+The name of the archive @command{tar} is processing.
+
+@vrindex TAR_BLOCKING_FACTOR, checkpoint script environment
+@item TAR_BLOCKING_FACTOR
+Current blocking factor (@pxref{Blocking}).
+
+@vrindex TAR_CHECKPOINT, checkpoint script environment
+@item TAR_CHECKPOINT
+Number of the checkpoint.
+
+@vrindex TAR_SUBCOMMAND, checkpoint script environment
+@item TAR_SUBCOMMAND
+A short option describing the operation @command{tar} is executing.
+@xref{Operations}, for a complete list of subcommand options.
+
+@vrindex TAR_FORMAT, checkpoint script environment
+@item TAR_FORMAT
+Format of the archive being processed. @xref{Formats}, for a complete
+list of archive format names.
+@end table
+
+These environment variables can also be passed as arguments to the
+command, provided that they are properly escaped, for example:
+
+@smallexample
+@kbd{tar -c -f arc.tar \
+ --checkpoint-action='exec=/sbin/cpoint $TAR_FILENAME'}
+@end smallexample
+
+@noindent
+Notice single quotes to prevent variable names from being expanded by
+the shell when invoking @command{tar}.
+
+Any number of actions can be defined, by supplying several
+@option{--checkpoint-action} options in the command line. For
+example, the command below displays two messages, pauses
+execution for 30 seconds and executes the @file{/sbin/cpoint} script:
+
+@example
+@group
+$ @kbd{tar -c -f arc.tar \
+ --checkpoint-action='\aecho=Hit %s checkpoint #%u' \
+ --checkpoint-action='echo=Sleeping for 30 seconds' \
+ --checkpoint-action='sleep=30' \
+ --checkpoint-action='exec=/sbin/cpoint'}
+@end group
+@end example
+
+This example also illustrates the fact that
+@option{--checkpoint-action} can be used without
+@option{--checkpoint}. In this case, the default checkpoint frequency
+(at each 10th record) is assumed.
+
+@node warnings
+@section Controlling Warning Messages
+
+Sometimes, while performing the requested task, @GNUTAR{} notices
+some conditions that are not exactly errors, but which the user
+should be aware of. When this happens, @command{tar} issues a
+@dfn{warning message} describing the condition. Warning messages
+are output to the standard error and they do not affect the exit
+code of @command{tar} command.
+
+@xopindex{warning, explained}
+@GNUTAR{} allows the user to suppress some or all of its warning
+messages:
+
+@table @option
+@item --warning=@var{keyword}
+Control display of the warning messages identified by @var{keyword}.
+If @var{keyword} starts with the prefix @samp{no-}, such messages are
+suppressed. Otherwise, they are enabled.
+
+Multiple @option{--warning} messages accumulate.
+
+The tables below list allowed values for @var{keyword} along with the
+warning messages they control.
+@end table
+
+@subheading Keywords controlling @command{tar} operation
+@table @asis
+@kwindex all
+@item all
+Enable all warning messages. This is the default.
+@kwindex none
+@item none
+Disable all warning messages.
+@kwindex filename-with-nuls
+@cindex @samp{file name read contains nul character}, warning message
+@item filename-with-nuls
+@samp{%s: file name read contains nul character}
+@kwindex alone-zero-block
+@cindex @samp{A lone zero block at}, warning message
+@item alone-zero-block
+@samp{A lone zero block at %s}
+@end table
+
+@subheading Keywords applicable for @command{tar --create}
+@table @asis
+@kwindex cachedir
+@cindex @samp{contains a cache directory tag}, warning message
+@item cachedir
+@samp{%s: contains a cache directory tag %s; %s}
+@kwindex file-shrank
+@cindex @samp{File shrank by %s bytes}, warning message
+@item file-shrank
+@samp{%s: File shrank by %s bytes; padding with zeros}
+@kwindex xdev
+@cindex @samp{file is on a different filesystem}, warning message
+@item xdev
+@samp{%s: file is on a different filesystem; not dumped}
+@kwindex file-ignored
+@cindex @samp{Unknown file type; file ignored}, warning message
+@cindex @samp{socket ignored}, warning message
+@cindex @samp{door ignored}, warning message
+@item file-ignored
+@samp{%s: Unknown file type; file ignored}
+@*@samp{%s: socket ignored}
+@*@samp{%s: door ignored}
+@kwindex file-unchanged
+@cindex @samp{file is unchanged; not dumped}, warning message
+@item file-unchanged
+@samp{%s: file is unchanged; not dumped}
+@kwindex ignore-archive
+@cindex @samp{file is the archive; not dumped}, warning message
+@kwindex ignore-archive
+@cindex @samp{file is the archive; not dumped}, warning message
+@item ignore-archive
+@samp{%s: file is the archive; not dumped}
+@kwindex file-removed
+@cindex @samp{File removed before we read it}, warning message
+@item file-removed
+@samp{%s: File removed before we read it}
+@kwindex file-changed
+@cindex @samp{file changed as we read it}, warning message
+@item file-changed
+@samp{%s: file changed as we read it}
+@end table
+
+@subheading Keywords applicable for @command{tar --extract}
+@table @asis
+@kwindex timestamp
+@cindex @samp{implausibly old time stamp %s}, warning message
+@cindex @samp{time stamp %s is %s s in the future}, warning message
+@item timestamp
+@samp{%s: implausibly old time stamp %s}
+@*@samp{%s: time stamp %s is %s s in the future}
+@kwindex contiguous-cast
+@cindex @samp{Extracting contiguous files as regular files}, warning message
+@item contiguous-cast
+@samp{Extracting contiguous files as regular files}
+@kwindex symlink-cast
+@cindex @samp{Attempting extraction of symbolic links as hard links}, warning message
+@item symlink-cast
+@samp{Attempting extraction of symbolic links as hard links}
+@kwindex unknown-cast
+@cindex @samp{Unknown file type '%c', extracted as normal file}, warning message
+@item unknown-cast
+@samp{%s: Unknown file type '%c', extracted as normal file}
+@kwindex ignore-newer
+@cindex @samp{Current %s is newer or same age}, warning message
+@item ignore-newer
+@samp{Current %s is newer or same age}
+@kwindex unknown-keyword
+@cindex @samp{Ignoring unknown extended header keyword '%s'}, warning message
+@item unknown-keyword
+@samp{Ignoring unknown extended header keyword '%s'}
+@kwindex decompress-program
+@item decompress-program
+Controls verbose description of failures occurring when trying to run
+alternative decompressor programs (@pxref{alternative decompression
+programs}). This warning is disabled by default (unless
+@option{--verbose} is used). A common example of what you can get
+when using this warning is:
+
+@smallexample
+$ @kbd{tar --warning=decompress-program -x -f archive.Z}
+tar (child): cannot run compress: No such file or directory
+tar (child): trying gzip
+@end smallexample
+
+This means that @command{tar} first tried to decompress
+@file{archive.Z} using @command{compress}, and, when that
+failed, switched to @command{gzip}.
+@kwindex record-size
+@cindex @samp{Record size = %lu blocks}, warning message
+@item record-size
+@samp{Record size = %lu blocks}
+@end table
+
+@subheading Keywords controlling incremental extraction:
+@table @asis
+@kwindex rename-directory
+@cindex @samp{%s: Directory has been renamed from %s}, warning message
+@cindex @samp{%s: Directory has been renamed}, warning message
+@item rename-directory
+@samp{%s: Directory has been renamed from %s}
+@*@samp{%s: Directory has been renamed}
+@kwindex new-directory
+@cindex @samp{%s: Directory is new}, warning message
+@item new-directory
+@samp{%s: Directory is new}
+@kwindex xdev
+@cindex @samp{%s: directory is on a different device: not purging}, warning message
+@item xdev
+@samp{%s: directory is on a different device: not purging}
+@kwindex bad-dumpdir
+@cindex @samp{Malformed dumpdir: 'X' never used}, warning message
+@item bad-dumpdir
+@samp{Malformed dumpdir: 'X' never used}
+@end table
+
@node interactive
@section Asking for Confirmation During Operations
@cindex Interactive operation
read from that named pipe. This has the advantage of letting standard
output free to receive verbose output, all separate from errors.
+@node external
+@section Running External Commands
+
+Certain @GNUTAR{} operations imply running external commands that you
+supply on the command line. One of such operations is checkpointing,
+described above (@pxref{checkpoint exec}). Another example of this
+feature is the @option{-I} option, which allows you to supply the
+program to use for compressing or decompressing the archive
+(@pxref{use-compress-program}).
+
+Whenever such operation is requested, @command{tar} first splits the
+supplied command into words much like the shell does. It then treats
+the first word as the name of the program or the shell script to execute
+and the rest of words as its command line arguments. The program,
+unless given as an absolute file name, is searched in the shell's
+@env{PATH}.
+
+Any additional information is normally supplied to external commands
+in environment variables, specific to each particular operation. For
+example, the @option{--checkpoint-action=exec} option, defines the
+@env{TAR_ARCHIVE} variable to the name of the archive being worked
+upon. You can, should the need be, use these variables in the
+command line of the external command. For example:
+
+@smallexample
+$ @kbd{tar -x -f archive.tar \
+ --checkpoint=exec='printf "%04d in %32s\r" $TAR_CHECKPOINT $TAR_ARCHIVE'}
+@end smallexample
+
+@noindent
+This command prints for each checkpoint its number and the name of the
+archive, using the same output line on the screen.
+
+Notice the use of single quotes to prevent variable names from being
+expanded by the shell when invoking @command{tar}.
+
@node operations
@chapter @GNUTAR{} Operations
@smallexample
@kbd{tar --create --file=empty-archive.tar --files-from=/dev/null}
-@kbd{tar cfT empty-archive.tar /dev/null}
+@kbd{tar -cf empty-archive.tar -T /dev/null}
@end smallexample
@xopindex{extract, complementary notes}
@node Operations
@subsection The Five Advanced @command{tar} Operations
-@UNREVISED
+@cindex basic operations
In the last chapter, you learned about the first three operations to
@command{tar}. This chapter presents the remaining five operations to
@command{tar}: @option{--append}, @option{--update}, @option{--concatenate},
will give examples using the same directory and files that you created
in the last chapter. As you may recall, the directory is called
@file{practice}, the files are @samp{jazz}, @samp{blues}, @samp{folk},
-@samp{rock}, and the two archive files you created are
+and the two archive files you created are
@samp{collection.tar} and @samp{music.tar}.
We will also use the archive files @samp{afiles.tar} and
@itemx -r
Add new entries to an archive that already exists.
@item --update
-@itemx -r
+@itemx -u
Add more recent copies of archive members to the end of an archive, if
they exist.
@item --concatenate
@node append
@subsection How to Add Files to Existing Archives: @option{--append}
-@UNREVISED
+@cindex appending files to existing archive
@opindex append
If you want to add files to an existing archive, you don't need to
create a new archive; you can use @option{--append} (@option{-r}).
Other operations don't deal with these members as perfectly as you might
prefer; if you were to use @option{--extract} to extract the archive,
-only the most recently added copy of a member with the same name as four
+only the most recently added copy of a member with the same name as
other members would end up in the working directory. This is because
@option{--extract} extracts an archive in the order the members appeared
in the archive; the most recently archived members will be extracted
last. Additionally, an extracted member will @emph{replace} a file of
the same name which existed in the directory already, and @command{tar}
will not prompt you about this@footnote{Unless you give it
-@option{--keep-old-files} option, or the disk copy is newer than the
-the one in the archive and you invoke @command{tar} with
-@option{--keep-newer-files} option}. Thus, only the most recently archived
-member will end up being extracted, as it will replace the one
-extracted before it, and so on.
-
+@option{--keep-old-files} (or @option{--skip-old-files}) option, or
+the disk copy is newer than the one in the archive and you invoke
+@command{tar} with @option{--keep-newer-files} option.}. Thus, only
+the most recently archived member will end up being extracted, as it
+will replace the one extracted before it, and so on.
+
+@cindex extracting @var{n}th copy of the file
+@xopindex{occurrence, described}
There exists a special option that allows you to get around this
behavior and extract (or list) only a particular copy of the file.
This is @option{--occurrence} option. If you run @command{tar} with
@FIXME{ hag -- you might want to incorporate some of the above into the
MMwtSN node; not sure. i didn't know how to make it simpler...
-There are a few ways to get around this. (maybe xref Multiple Members
-with the Same Name.}
+There are a few ways to get around this. Xref to Multiple Members
+with the Same Name, maybe.}
@cindex Members, replacing with other members
@cindex Replacing members with other members
+@xopindex{delete, using before --append}
If you want to replace an archive member, use @option{--delete} to
-delete the member you want to remove from the archive, , and then use
+delete the member you want to remove from the archive, and then use
@option{--append} to add the member you want to be in the archive. Note
that you can not change the order of the archive; the most recently
added member will still appear last. In this sense, you cannot truly
@node appending files
@subsubsection Appending Files to an Archive
-@UNREVISED
@cindex Adding files to an Archive
@cindex Appending files to an Archive
@cindex Archives, Appending files to
+@opindex append
The simplest way to add a file to an already existing archive is the
@option{--append} (@option{-r}) operation, which writes specified
@smallexample
$ @kbd{tar --list --file=collection.tar}
--rw-r--r-- me user 28 1996-10-18 16:31 jazz
--rw-r--r-- me user 21 1996-09-23 16:44 blues
--rw-r--r-- me user 20 1996-09-23 16:44 folk
--rw-r--r-- me user 20 1996-09-23 16:44 rock
+-rw-r--r-- me/user 28 1996-10-18 16:31 jazz
+-rw-r--r-- me/user 21 1996-09-23 16:44 blues
+-rw-r--r-- me/user 20 1996-09-23 16:44 folk
+-rw-r--r-- me/user 20 1996-09-23 16:44 rock
@end smallexample
@node multiple
@subsubsection Multiple Members with the Same Name
+@cindex members, multiple
+@cindex multiple members
You can use @option{--append} (@option{-r}) to add copies of files
which have been updated since the archive was created. (However, we
@smallexample
$ @kbd{tar --list --verbose --file=collection.tar}
--rw-r--r-- me user 28 1996-10-18 16:31 jazz
--rw-r--r-- me user 21 1996-09-23 16:44 blues
--rw-r--r-- me user 20 1996-09-23 16:44 folk
--rw-r--r-- me user 20 1996-09-23 16:44 rock
--rw-r--r-- me user 58 1996-10-24 18:30 blues
+-rw-r--r-- me/user 28 1996-10-18 16:31 jazz
+-rw-r--r-- me/user 21 1996-09-23 16:44 blues
+-rw-r--r-- me/user 20 1996-09-23 16:44 folk
+-rw-r--r-- me/user 20 1996-09-23 16:44 rock
+-rw-r--r-- me/user 58 1996-10-24 18:30 blues
@end smallexample
@noindent
@smallexample
$ @kbd{tar --extract -vv --occurrence --file=collection.tar blues}
--rw-r--r-- me user 21 1996-09-23 16:44 blues
+-rw-r--r-- me/user 21 1996-09-23 16:44 blues
@end smallexample
@xref{Writing}, for more information on @option{--extract} and
-@xref{Option Summary, --occurrence}, for the description of
+see @ref{Option Summary, --occurrence}, for a description of
@option{--occurrence} option.
@node update
@subsection Updating an Archive
-@UNREVISED
@cindex Updating an archive
-
@opindex update
+
In the previous section, you learned how to use @option{--append} to
add a file to an existing archive. A related operation is
@option{--update} (@option{-u}). The @option{--update} operation
@node how to update
@subsubsection How to Update an Archive Using @option{--update}
+@opindex update
You must use file name arguments with the @option{--update}
(@option{-u}) operation. If you don't specify any files,
@file{classical}, in your practice directory, and some extra text to the
file @file{blues}, using any text editor. Then invoke @command{tar} with
the @samp{update} operation and the @option{--verbose} (@option{-v})
-option specified, using the names of all the files in the practice
+option specified, using the names of all the files in the @file{practice}
directory as file name arguments:
@smallexample
the one at the end will be newer and larger, since you added text before
updating it.
-(The reason @command{tar} does not overwrite the older file when updating
+The reason @command{tar} does not overwrite the older file when updating
it is because writing to the middle of a section of tape is a difficult
process. Tapes are not designed to go backward. @xref{Media}, for more
information about tapes.
To use @option{--concatenate}, give the first archive with
@option{--file} option and name the rest of archives to be
concatenated on the command line. The members, and their member
-names, will be copied verbatim from those archives to the first one.
-@footnote{This can cause multiple members to have the same name, for
-information on how this affects reading the archive, @ref{multiple}.}
+names, will be copied verbatim from those archives to the first
+one@footnote{This can cause multiple members to have the same name. For
+information on how this affects reading the archive, see @ref{multiple}.}.
The new, concatenated archive will be called by the same name as the
one given with the @option{--file} option. As usual, if you omit
@option{--file}, @command{tar} will use the value of the environment
@smallexample
$ @kbd{tar -tvf bluesrock.tar}
--rw-r--r-- melissa user 105 1997-01-21 19:42 blues
--rw-r--r-- melissa user 33 1997-01-20 15:34 rock
+-rw-r--r-- melissa/user 105 1997-01-21 19:42 blues
+-rw-r--r-- melissa/user 33 1997-01-20 15:34 rock
$ @kbd{tar -tvf jazzfolk.tar}
--rw-r--r-- melissa user 20 1996-09-23 16:44 folk
--rw-r--r-- melissa user 65 1997-01-30 14:15 jazz
+-rw-r--r-- melissa/user 20 1996-09-23 16:44 folk
+-rw-r--r-- melissa/user 65 1997-01-30 14:15 jazz
@end smallexample
We can concatenate these two archives with @command{tar}:
@node delete
@subsection Removing Archive Members Using @option{--delete}
-@UNREVISED
@cindex Deleting files from an archive
@cindex Removing files from an archive
folk
jazz
rock
-$
@end smallexample
@FIXME{Check if the above listing is actually produced after running
@node compare
@subsection Comparing Archive Members with the File System
@cindex Verifying the currency of an archive
-@UNREVISED
@opindex compare
The @option{--compare} (@option{-d}), or @option{--diff} operation compares
The spirit behind the @option{--compare} (@option{--diff},
@option{-d}) option is to check whether the archive represents the
current state of files on disk, more than validating the integrity of
-the archive media. For this later goal, @xref{verify}.
+the archive media. For this latter goal, see @ref{verify}.
@node create options
@section Options Used by @option{--create}
the modification time of members when creating archives, instead of
their actual modification times. The argument @var{date} can be
either a textual date representation in almost arbitrary format
-(@pxref{Date input formats}) or a name of the existing file, starting
+(@pxref{Date input formats}) or a name of an existing file, starting
with @samp{/} or @samp{.}. In the latter case, the modification time
of that file will be used.
-The following example will set the modification date to 00:00:00 UTC,
+The following example will set the modification date to 00:00:00,
January 1, 1970:
@smallexample
@smallexample
$ @kbd{tar -c -f archive.tar -v --mtime=yesterday .}
-tar: Option --mtime: Treating date `yesterday' as 2006-06-20
+tar: Option --mtime: Treating date 'yesterday' as 2006-06-20
13:06:29.152478
@dots{}
@end smallexample
Specifies that @command{tar} should use @var{user} as the owner of members
when creating archives, instead of the user associated with the source
-file. The argument @var{user} can be either an existing user symbolic
-name, or a decimal numeric user @acronym{ID}.
+file.
+
+If @var{user} contains a colon, it is taken to be of the form
+@var{name}:@var{id} where a nonempty @var{name} specifies the user
+name and a nonempty @var{id} specifies the decimal numeric user
+@acronym{ID}. If @var{user} does not contain a colon, it is taken to
+be a user number if it is one or more decimal digits; otherwise it is
+taken to be a user name.
+
+If a name is given but no number, the number is inferred from the
+current host's user database if possible, and the file's user number
+is used otherwise. If a number is given but no name, the name is
+inferred from the number if possible, and an empty name is used
+otherwise. If both name and number are given, the user database is
+not consulted, and the name and number need not be valid on the
+current host.
There is no value indicating a missing number, and @samp{0} usually means
@code{root}. Some people like to force @samp{0} as the value to offer in
archives. For example:
@smallexample
-@group
$ @kbd{tar -c -f archive.tar --owner=0 .}
-# @r{Or:}
+@end smallexample
+
+@noindent
+or:
+
+@smallexample
$ @kbd{tar -c -f archive.tar --owner=root .}
-@end group
@end smallexample
@item --group=@var{group}
@opindex group
Files added to the @command{tar} archive will have a group @acronym{ID} of @var{group},
-rather than the group from the source file. The argument @var{group}
-can be either an existing group symbolic name, or a decimal numeric group @acronym{ID}.
+rather than the group from the source file. As with @option{--owner},
+the argument @var{group} can be an existing group symbolic name, or a
+decimal numeric group @acronym{ID}, or @var{name}:@var{id}.
@end table
@node Ignore Failed Read
@node extract options
@section Options Used by @option{--extract}
-@UNREVISED
+@cindex options for use with @option{--extract}
@xopindex{extract, additional options}
The previous chapter showed how to use @option{--extract} to extract
@node Reading
@subsection Options to Help Read Archives
@cindex Options when reading archives
-@UNREVISED
@cindex Reading incomplete records
@cindex Records, incomplete
@cindex Overwriting old files, prevention
@xopindex{keep-old-files, introduced}
To be even more cautious and prevent existing files from being replaced, use
-the @option{--keep-old-files} (@option{-k}) option. It causes @command{tar} to refuse
-to replace or update a file that already exists, i.e., a file with the
-same name as an archive member prevents extraction of that archive
-member. Instead, it reports an error.
+the @option{--keep-old-files} (@option{-k}) option. It causes
+@command{tar} to refuse to replace or update a file that already
+exists, i.e., a file with the same name as an archive member prevents
+extraction of that archive member. Instead, it reports an error. For
+example:
+
+@example
+$ @kbd{ls}
+blues
+$ @kbd{tar -x -k -f archive.tar}
+tar: blues: Cannot open: File exists
+tar: Exiting with failure status due to previous errors
+@end example
+
+@xopindex{skip-old-files, introduced}
+If you wish to preserve old files untouched, but don't want
+@command{tar} to treat them as errors, use the
+@option{--skip-old-files} option. This option causes @command{tar} to
+silently skip extracting over existing files.
@xopindex{overwrite, introduced}
To be more aggressive about altering existing files, use the
@node Keep Old Files
@unnumberedsubsubsec Keep Old Files
+@GNUTAR{} provides two options to control its actions in a situation
+when it is about to extract a file which already exists on disk.
+
@table @option
@opindex keep-old-files
@item --keep-old-files
@itemx -k
-Do not replace existing files from archive. The
-@option{--keep-old-files} (@option{-k}) option prevents @command{tar}
-from replacing existing files with files with the same name from the
-archive. The @option{--keep-old-files} option is meaningless with
-@option{--list} (@option{-t}). Prevents @command{tar} from replacing
-files in the file system during extraction.
+Do not replace existing files from archive. When such a file is
+encountered, @command{tar} issues an error message. Upon end of
+extraction, @command{tar} exits with code 2 (@pxref{exit status}).
+
+@item --skip-old-files
+Do not replace existing files from archive, but do not treat that
+as error. Such files are silently skipped and do not affect
+@command{tar} exit status.
+
+Additional verbosity can be obtained using @option{--warning=existing-file}
+together with that option (@pxref{warnings}).
@end table
@node Keep Newer Files
directory timestamp will be offset again.
To correctly restore directory meta-information in such cases, use
-@option{delay-directory-restore} command line option:
+the @option{--delay-directory-restore} command line option:
@table @option
@opindex delay-directory-restore
@opindex to-command
@item --to-command=@var{command}
Extract files and pipe their contents to the standard input of
-@var{command}. When this option is used, instead of creating the
+@var{command}. When this option is used, instead of creating the
files specified, @command{tar} invokes @var{command} and pipes the
-contents of the files to its standard output. @var{Command} may
-contain command line arguments. The program is executed via
-@code{sh -c}. Notice, that @var{command} is executed once for each regular file
+contents of the files to its standard output. The @var{command} may
+contain command line arguments (see @ref{external, Running External Commands},
+for more detail).
+
+Notice, that @var{command} is executed once for each regular file
extracted. Non-regular files (directories, etc.) are ignored when this
option is used.
@end table
The command can obtain the information about the file it processes
from the following environment variables:
-@table @var
+@table @env
@vrindex TAR_FILETYPE, to-command environment
@item TAR_FILETYPE
Type of the file. It is a single letter with the following meaning:
@vrindex TAR_ATIME, to-command environment
@item TAR_ATIME
Time of last access. It is a decimal number, representing seconds
-since the epoch. If the archive provides times with nanosecond
+since the Epoch. If the archive provides times with nanosecond
precision, the nanoseconds are appended to the timestamp after a
decimal point.
GID of the file owner.
@end table
-In addition to these variables, @env{TAR_VERSION} contains the
+Additionally, the following variables contain information about
+tar mode and the archive being processed:
+
+@table @env
+@vrindex TAR_VERSION, to-command environment
+@item TAR_VERSION
@GNUTAR{} version number.
+@vrindex TAR_ARCHIVE, to-command environment
+@item TAR_ARCHIVE
+The name of the archive @command{tar} is processing.
+
+@vrindex TAR_BLOCKING_FACTOR, to-command environment
+@item TAR_BLOCKING_FACTOR
+Current blocking factor (@pxref{Blocking}).
+
+@vrindex TAR_VOLUME, to-command environment
+@item TAR_VOLUME
+Ordinal number of the volume @command{tar} is processing.
+
+@vrindex TAR_FORMAT, to-command environment
+@item TAR_FORMAT
+Format of the archive being processed. @xref{Formats}, for a complete
+list of archive format names.
+@end table
+
+These variables are defined prior to executing the command, so you can
+pass them as arguments, if you prefer. For example, if the command
+@var{proc} takes the member name and size as its arguments, then you
+could do:
+
+@smallexample
+$ @kbd{tar -x -f archive.tar \
+ --to-command='proc $TAR_FILENAME $TAR_SIZE'}
+@end smallexample
+
+@noindent
+Notice single quotes to prevent variable names from being expanded by
+the shell when invoking @command{tar}.
+
If @var{command} exits with a non-0 status, @command{tar} will print
an error message similar to the following:
archive. This assumes, of course, that there is now free space, or
that you are now extracting into a different file system. (You could
also choose to suspend @command{tar}, remove unnecessary files from
-the file system, and then restart the same @command{tar} operation.
-In this case, @option{--starting-file} is not necessary.
-@xref{Incremental Dumps}, @xref{interactive}, and @ref{exclude}.)
+the file system, and then resume the same @command{tar} operation.
+In this case, @option{--starting-file} is not necessary.) See also
+@ref{interactive}, and @ref{exclude}.
@node Same Order
@unnumberedsubsubsec Same Order
Backup options may prove unexpectedly useful when extracting archives
containing many members having identical name, or when extracting archives
on systems having file name limitations, making different members appear
-has having similar names through the side-effect of name truncation.
-(This is true only if we have a good scheme for truncated backup names,
-which I'm not sure at all: I suspect work is needed in this area.)
+as having similar names through the side-effect of name truncation.
+@FIXME{This is true only if we have a good scheme for truncated backup names,
+which I'm not sure at all: I suspect work is needed in this area.}
When any existing file is backed up before being overwritten by extraction,
then clashing files are automatically be renamed to be unique, and the
true name is kept for only the last file of a series of clashing files.
For example, here is how you might copy a directory's contents from
one disk to another, while preserving the dates, modes, owners and
link-structure of all the files therein. In this case, the transfer
-medium is a @dfn{pipe}, which is one a Unix redirection mechanism:
+medium is a @dfn{pipe}:
@smallexample
$ @kbd{(cd sourcedir; tar -cf - .) | (cd targetdir; tar -xf -)}
@end smallexample
@noindent
-The command also works using short option forms:
+The command also works using long option forms:
@smallexample
+@group
$ @kbd{(cd sourcedir; tar --create --file=- . ) \
| (cd targetdir; tar --extract --file=-)}
-# Or:
-$ @kbd{tar --directory sourcedir --create --file=- . ) \
+@end group
+@end smallexample
+
+@noindent
+or
+
+@smallexample
+@group
+$ @kbd{tar --directory sourcedir --create --file=- . \
| tar --directory targetdir --extract --file=-}
+@end group
@end smallexample
@noindent
@node Backups
@chapter Performing Backups and Restoring Files
-@UNREVISED
+@cindex backups
-@GNUTAR{} is distributed along with the scripts
-which the Free Software Foundation uses for performing backups. There
-is no corresponding scripts available yet for doing restoration of
-files. Even if there is a good chance those scripts may be satisfying
-to you, they are not the only scripts or methods available for doing
+@GNUTAR{} is distributed along with the scripts for performing backups
+and restores. Even if there is a good chance those scripts may be
+satisfying to you, they are not the only scripts or methods available for doing
backups and restore. You may well create your own, or use more
sophisticated packages dedicated to that purpose.
Some users are enthusiastic about @code{Amanda} (The Advanced Maryland
Automatic Network Disk Archiver), a backup system developed by James
da Silva @file{jds@@cs.umd.edu} and available on many Unix systems.
-This is free software, and it is available at these places:
-
-@smallexample
-http://www.cs.umd.edu/projects/amanda/amanda.html
-ftp://ftp.cs.umd.edu/pub/amanda
-@end smallexample
+This is free software, and it is available from @uref{http://www.amanda.org}.
@FIXME{
backups: @option{--listed-incremental=@var{snapshot-file}} (@option{-g
@var{snapshot-file}}) and @option{--incremental} (@option{-G}).
-@opindex listed-incremental
+@xopindex{listed-incremental, described}
The option @option{--listed-incremental} instructs tar to operate on
an incremental archive with additional metadata stored in a standalone
file, called a @dfn{snapshot file}. The purpose of this file is to help
/usr}
@end smallexample
+@anchor{--level=0}
+@xopindex{level, described}
+You can force @samp{level 0} backups either by removing the snapshot
+file before running @command{tar}, or by supplying the
+@option{--level=0} option, e.g.:
+
+@smallexample
+$ @kbd{tar --create \
+ --file=archive.2.tar \
+ --listed-incremental=/var/log/usr.snar-0 \
+ --level=0 \
+ /usr}
+@end smallexample
+
Incremental dumps depend crucially on time stamps, so the results are
unreliable if you modify a file's time stamps during dumping (e.g.,
with the @option{--atime-preserve=replace} option), or if you set the clock
backwards.
+@anchor{device numbers}
@cindex Device numbers, using in incremental backups
Metadata stored in snapshot files include device numbers, which,
-obviously is supposed to be a non-volatile value. However, it turns
-out that NFS devices have undependable values when an automounter
+obviously are supposed to be non-volatile values. However, it turns
+out that @acronym{NFS} devices have undependable values when an automounter
gets in the picture. This can lead to a great deal of spurious
redumping in incremental dumps, so it is somewhat useless to compare
-two NFS devices numbers over time. The solution implemented currently
-is to considers all NFS devices as being equal when it comes to
-comparing directories; this is fairly gross, but there does not seem
-to be a better way to go.
+two @acronym{NFS} devices numbers over time. The solution implemented
+currently is to consider all @acronym{NFS} devices as being equal
+when it comes to comparing directories; this is fairly gross, but
+there does not seem to be a better way to go.
+
+Apart from using @acronym{NFS}, there are a number of cases where
+relying on device numbers can cause spurious redumping of unmodified
+files. For example, this occurs when archiving @acronym{LVM} snapshot
+volumes. To avoid this, use @option{--no-check-device} option:
+
+@table @option
+@xopindex{no-check-device, described}
+@item --no-check-device
+Do not rely on device numbers when preparing a list of changed files
+for an incremental dump.
+
+@xopindex{check-device, described}
+@item --check-device
+Use device numbers when preparing a list of changed files
+for an incremental dump. This is the default behavior. The purpose
+of this option is to undo the effect of the @option{--no-check-device}
+if it was given in @env{TAR_OPTIONS} environment variable
+(@pxref{TAR_OPTIONS}).
+@end table
-If you are using the @i{Linux} kernel, the device numbers can also
-change when upgrading to some newer versions of the kernel. This can
-cause the next backup to be full backup on the affected filesystems.
-@xref{Fixing Snapshot Files}, for the information on how to handle this case.
+There is also another way to cope with changing device numbers. It is
+described in detail in @ref{Fixing Snapshot Files}.
Note that incremental archives use @command{tar} extensions and may
not be readable by non-@acronym{GNU} versions of the @command{tar} program.
Alternatively, you can use @option{--incremental}, which needs no
arguments. In general, @option{--incremental} (@option{-G}) can be
used as a shortcut for @option{--listed-incremental} when listing or
-extracting incremental backups (for more information, regarding this
+extracting incremental backups (for more information regarding this
option, @pxref{incremental-op}).
When extracting from the incremental backup @GNUTAR{} attempts to
@option{--incremental} or @option{--listed-incremental} option was
given, no matter what the verbosity level. This behavior, and,
especially, the binary output it produced were considered inconvenient
-and were changed in version 1.16}:
+and were changed in version 1.16.}:
@smallexample
@kbd{tar --list --incremental --verbose --verbose archive.tar}
only extracting two archives---the last weekly (full) dump and the
last daily (level one) dump. The only information lost would be in
files changed or created since the last daily backup. (Doing dumps
-more than once a day is usually not worth the trouble).
+more than once a day is usually not worth the trouble.)
@GNUTAR{} comes with scripts you can use to do full
and level-one (actually, even level-two and so on) dumps. Using
machine where the scripts are run (i.e., what @command{pwd} will print
when in that directory on that machine). If the host that contains
the file system does not have this capability, you can specify another
-host as long as it can access the file system through NFS.
+host as long as it can access the file system through @acronym{NFS}.
If the list of file systems is very long you may wish to put it
in a separate file. This file is usually named
(for @code{restore}). These should be accessible from the machine on
which the backup script is run.
-If the list of file systems is very long you may wish to store it
+If the list of individual files is very long you may wish to store it
in a separate file. This file is usually named
@file{/etc/backup/files}, but this name may be overridden in
@file{backup-specs} using @code{FILELIST} variable.
@subsection Magnetic Tape Control
Backup scripts access tape device using special @dfn{hook functions}.
-These functions take a single argument -- the name of the tape
+These functions take a single argument --- the name of the tape
device. Their names are kept in the following variables:
@defvr {Backup variable} MT_BEGIN
@end table
@end deffn
-Following variables keep the names of user hook functions
+Following variables keep the names of user hook functions:
@defvr {Backup variable} DUMP_BEGIN
Dump begin function. It is executed before dumping the file system.
backup --level=@var{level} --time=@var{time}
@end smallexample
-The @option{level} option requests the dump level. Thus, to produce
+The @option{--level} option requests the dump level. Thus, to produce
a full dump, specify @code{--level=0} (this is the default, so
-@option{--level} may be omitted if its value is @code{0}).
-@footnote{For backward compatibility, the @code{backup} will also
+@option{--level} may be omitted if its value is
+@code{0})@footnote{For backward compatibility, the @code{backup} will also
try to deduce the requested dump level from the name of the
script itself. If the name consists of a string @samp{level-}
followed by a single decimal digit, that digit is taken as
the dump level number. Thus, you may create a link from @code{backup}
to @code{level-1} and then run @code{level-1} whenever you need to
-create a level one dump.}
+create a level one dump.}.
The @option{--time} option determines when should the backup be
run. @var{Time} may take three forms:
@item @var{hh}
-The dump must be run at @var{hh} hours
+The dump must be run at @var{hh} hours.
@item now
@file{backup-specs} (@pxref{General-Purpose Variables,BACKUP_DIRS}).
You may select the file systems (and/or files) to restore by
-giving @code{restore} list of @dfn{patterns} in its command
+giving @code{restore} a list of @dfn{patterns} in its command
line. For example, running
@smallexample
@table @option
@item -a
@itemx --all
-Restore all file systems and files specified in @file{backup-specs}
+Restore all file systems and files specified in @file{backup-specs}.
@item -l @var{level}
@itemx --level=@var{level}
@node Choosing
@chapter Choosing Files and Names for @command{tar}
-@UNREVISED
Certain options to @command{tar} enable you to specify a name for your
archive. Other options let you decide which files to include or exclude
@node file
@section Choosing and Naming Archive Files
-@UNREVISED
@cindex Naming an archive
@cindex Archive Name
@cindex Choosing an archive file
@cindex Where is the archive?
+@opindex file
By default, @command{tar} uses an archive file name that was compiled when
it was built on the system; usually this name refers to some physical
tape drive on the machine. However, the person who installed @command{tar}
@end smallexample
@noindent
-@command{tar} will complete the remote connection, if possible, and
+@command{tar} will set up the remote connection, if possible, and
prompt you for a username and password. If you use
@option{--file=@@@var{hostname}:/@var{dev}/@var{file-name}}, @command{tar}
-will complete the remote connection, if possible, using your username
+will attempt to set up the remote connection using your username
as the username on the remote machine.
@cindex Local and remote archives
(along with the @samp{@@} sign), then your user name will be used.
(This is the normal @command{rsh} behavior.) It is necessary for the
remote machine, in addition to permitting your @command{rsh} access, to
-have the @file{rmt} program installed (This command is included in
+have the @file{rmt} program installed (this command is included in
the @GNUTAR{} distribution and by default is installed under
-@file{@var{prefix}/libexec/rmt}, were @var{prefix} means your
+@file{@var{prefix}/libexec/rmt}, where @var{prefix} means your
installation prefix). If you need to use a file whose name includes a
colon, then the remote tape drive behavior
can be inhibited by using the @option{--force-local} option.
@group
$ @kbd{tar cf a.tar}
tar: Cowardly refusing to create an empty archive
-Try `tar --help' or `tar --usage' for more information.
+Try 'tar --help' or 'tar --usage' for more information.
@end group
@end smallexample
@cindex Reading file names from a file
@cindex Lists of file names
@cindex File Name arguments, alternatives
+@cindex @command{find}, using with @command{tar}
Instead of giving the names of files or archive members on the command
line, you can put the names into a file, and then use the
@option{--files-from=@var{file-of-names}} (@option{-T
more information.)
@smallexample
-$ @kbd{find . -size -400 -print > small-files}
+$ @kbd{find . -size -400 -print > small-files}
$ @kbd{tar -c -v -z -T small-files -f little.tgz}
@end smallexample
@noindent
In the file list given by @option{-T} option, any file name beginning
with @samp{-} character is considered a @command{tar} option and is
-processed accordingly.@footnote{Versions of @GNUTAR{} up to 1.15.1
+processed accordingly@footnote{Versions of @GNUTAR{} up to 1.15.1
recognized only @option{-C} option in file lists, and only if the
-option and its argument occupied two consecutive lines.} For example,
+option and its argument occupied two consecutive lines.}. For example,
the common use of this feature is to change to another directory by
specifying @option{-C} option:
@end group
@end smallexample
-@noindent
-@xopindex{directory, using in @option{--files-from} argument}
-Notice that the option parsing algorithm used with @option{-T} is
-stricter than the one used by shell. Namely, when specifying option
-arguments, you should observe the following rules:
-
-@itemize @bullet
-@item
-When using short (single-letter) option form, its argument must
-immediately follow the option letter, without any intervening
-whitespace. For example: @code{-Cdir}.
-
-@item
-When using long option form, the option argument must be separated
-from the option by a single equal sign. No whitespace is allowed on
-any side of the equal sign. For example: @code{--directory=dir}.
-
-@item
-For both short and long option forms, the option argument can be given
-on the next line after the option name, e.g.:
-
-@smallexample
-@group
---directory
-dir
-@end group
-@end smallexample
-
-@noindent
-and
-
-@smallexample
-@group
--C
-dir
-@end group
-@end smallexample
-@end itemize
-
@opindex add-file
If you happen to have a file whose name starts with @samp{-},
precede it with @option{--add-file} option to prevent it from
@end menu
@node nul
-@subsection @code{NUL} Terminated File Names
+@subsection @code{NUL}-Terminated File Names
@cindex File names, terminated by @code{NUL}
-@cindex @code{NUL} terminated file names
+@cindex @code{NUL}-terminated file names
The @option{--null} option causes
@option{--files-from=@var{file-of-names}} (@option{-T @var{file-of-names}})
to read file names terminated by a @code{NUL} instead of a newline, so
@option{--files-from}.
@table @option
-@opindex null
+@xopindex{null, described}
@item --null
-Only consider @code{NUL} terminated file names, instead of files that
+Only consider @code{NUL}-terminated file names, instead of files that
terminate in a newline.
+
+@xopindex{no-null, described}
+@item --no-null
+Undo the effect of any previous @option{--null} option.
@end table
The @option{--null} option is just like the one in @acronym{GNU}
@file{long-files}. The @option{-print0} option to @command{find} is just
like @option{-print}, except that it separates files with a @code{NUL}
rather than with a newline. You can then run @command{tar} with both the
-@option{--null} and @option{-T} options to specify that @command{tar} get the
+@option{--null} and @option{-T} options to specify that @command{tar} gets the
files from that file, @file{long-files}, to create the archive
@file{big.tgz}. The @option{--null} option to @command{tar} will cause
@command{tar} to recognize the @code{NUL} separator between files.
@smallexample
-$ @kbd{find . -size +800 -print0 > long-files}
+$ @kbd{find . -size +800 -print0 > long-files}
$ @kbd{tar -c -v --null --files-from=long-files --file=big.tar}
@end smallexample
-@FIXME{say anything else here to conclude the section?}
+The @option{--no-null} option can be used if you need to read both
+@code{NUL}-terminated and newline-terminated files on the same command line.
+For example, if @file{flist} is a newline-terminated file, then the
+following command can be used to combine it with the above command:
+
+@smallexample
+@group
+$ @kbd{find . -size +800 -print0 |
+ tar -c -f big.tar --null -T - --no-null -T flist}
+@end group
+@end smallexample
+
+This example uses short options for typographic reasons, to avoid
+very long lines.
+
+@GNUTAR is tries to automatically detect @code{NUL}-terminated file
+lists, so in many cases it is safe to use them even without the
+@option{--null} option. In this case @command{tar} will print a
+warning and continue reading such a file as if @option{--null} were
+actually given:
+
+@smallexample
+@group
+$ @kbd{find . -size +800 -print0 | tar -c -f big.tar -T -}
+tar: -: file name read contains nul character
+@end group
+@end smallexample
+
+The null terminator, however, remains in effect only for this
+particular file, any following @option{-T} options will assume
+newline termination. Of course, the null autodetection applies
+to these eventual surplus @option{-T} options as well.
@node exclude
@section Excluding Some Files
-@UNREVISED
@cindex File names, excluding files by
@cindex Excluding files by name and pattern
@cindex Excluding files by file system
+@opindex exclude
+@opindex exclude-from
To avoid operating on files whose names match a particular pattern,
use the @option{--exclude} or @option{--exclude-from} options.
However, empty lines are OK.
+@table @option
@cindex version control system, excluding files
@cindex VCS, excluding files
@cindex SCCS, excluding files
@cindex CVS, excluding files
@cindex SVN, excluding files
@cindex git, excluding files
-@table @option
+@cindex Bazaar, excluding files
+@cindex Arch, excluding files
+@cindex Mercurial, excluding files
+@cindex Darcs, excluding files
@opindex exclude-vcs
@item --exclude-vcs
-Exclude files and directories used by some version control systems.
-@end table
+Exclude files and directories used by following version control
+systems: @samp{CVS}, @samp{RCS}, @samp{SCCS}, @samp{SVN}, @samp{Arch},
+@samp{Bazaar}, @samp{Mercurial}, and @samp{Darcs}.
As of version @value{VERSION}, the following files are excluded:
@item @file{=RELEASE-ID}
@item @file{=meta-update}
@item @file{=update}
+@item @file{.bzr}
+@item @file{.bzrignore}
+@item @file{.bzrtags}
+@item @file{.hg}
+@item @file{.hgignore}
+@item @file{.hgrags}
+@item @file{_darcs}
@end itemize
+@opindex exclude-backups
+@item --exclude-backups
+Exclude backup and lock files. This option causes exclusion of files
+that match the following shell globbing patterns:
+
+@table @asis
+@item .#*
+@item *~
+@item #*#
+@end table
+
+@end table
+
@findex exclude-caches
When creating an archive, the @option{--exclude-caches} option family
causes @command{tar} to exclude all directories that contain a @dfn{cache
@itemize @bullet
@item Non-printable control characters:
-
+@anchor{escape sequences}
@multitable @columnfractions 0.20 0.10 0.60
@headitem Character @tab @acronym{ASCII} @tab Character name
@item \a @tab 7 @tab Audible bell
./a'single'quote
./a"double"quote
./a\backslash
-./a tab
+./a tab
./a
newline
@end group
'./a'\''single'\''quote'
'./a"double"quote'
'./a\backslash'
-'./a tab'
+'./a tab'
'./a
newline'
@end group
'./a'\''single'\''quote'
'./a"double"quote'
'./a\backslash'
-'./a tab'
+'./a tab'
'./a
newline'
@end group
Control characters, single quote and backslash are printed using
backslash notation. All names are quoted using left and right
quotation marks, appropriate to the current locale. If it does not
-define quotation marks, use @samp{`} as left and @samp{'} as right
+define quotation marks, use @samp{'} as left and as right
quotation marks. Any occurrences of the right quotation mark in a
name are escaped with @samp{\}, for example:
@smallexample
@group
$ @kbd{tar tf arch.tar --quoting-style=locale}
-`./'
-`./a space'
-`./a\'single\'quote'
-`./a"double"quote'
-`./a\\backslash'
-`./a\ttab'
-`./a\nnewline'
+'./'
+'./a space'
+'./a\'single\'quote'
+'./a"double"quote'
+'./a\\backslash'
+'./a\ttab'
+'./a\nnewline'
@end group
@end smallexample
@command{Tar} archives contain detailed information about files stored
in them and full file names are part of that information. When
-storing file to an archive, its file name is recorded in the archive
+storing a file to an archive, its file name is recorded in it,
along with the actual file contents. When restoring from an archive,
a file is created on disk with exactly the same name as that stored
in the archive. In the majority of cases this is the desired behavior
cases it is desirable to store files under differing names in the
archive.
-@GNUTAR{} provides two options for these needs.
+@GNUTAR{} provides several options for these needs.
@table @option
@opindex strip-components
two leading components (@file{usr/} and @file{include/}) off the file
name.
-If you add to the above invocation @option{--verbose} (@option{-v})
-option, you will note that the verbose listing still contains the
+If you add the @option{--verbose} (@option{-v}) option to the invocation
+above, you will note that the verbose listing still contains the
full file name, with the two removed components still in place. This
can be inconvenient, so @command{tar} provides a special option for
altering this behavior:
@end group
@end smallexample
-Notice that in both cases the file is @file{stdlib.h} extracted to the
+Notice that in both cases the file @file{stdlib.h} is extracted to the
current working directory, @option{--show-transformed-names} affects
only the way its name is displayed.
@table @option
@opindex transform
+@opindex xform
@item --transform=@var{expression}
+@itemx --xform=@var{expression}
Modify file names using supplied @var{expression}.
@end table
@var{regexp} and @var{replace} are described in detail in
@ref{The "s" Command, The "s" Command, The `s' Command, sed, GNU sed}.
+Any delimiter can be used in lieu of @samp{/}, the only requirement being
+that it be used consistently throughout the expression. For example,
+the following two expressions are equivalent:
+
+@smallexample
+@group
+s/one/two/
+s,one,two,
+@end group
+@end smallexample
+
+Changing delimiters is often useful when the @var{regex} contains
+slashes. For example, it is more convenient to write @code{s,/,-,} than
+@code{s/\//-/}.
+
+As in @command{sed}, you can give several replace expressions,
+separated by a semicolon.
+
Supported @var{flags} are:
@table @samp
just the first.
@item i
-Use case-insensitive matching
+Use case-insensitive matching.
@item x
@var{regexp} is an @dfn{extended regular expression} (@pxref{Extended
@item @var{number}
Only replace the @var{number}th match of the @var{regexp}.
-Note: the @var{posix} standard does not specify what should happen
+Note: the @acronym{POSIX} standard does not specify what should happen
when you mix the @samp{g} and @var{number} modifiers. @GNUTAR{}
follows the GNU @command{sed} implementation in this regard, so
the interaction is defined to be: ignore matches before the
@end table
-Any delimiter can be used in lieue of @samp{/}, the only requirement being
-that it be used consistently throughout the expression. For example,
-the following two expressions are equivalent:
+In addition, several @dfn{transformation scope} flags are supported,
+that control to what files transformations apply. These are:
+
+@table @samp
+@item r
+Apply transformation to regular archive members.
+
+@item R
+Do not apply transformation to regular archive members.
+
+@item s
+Apply transformation to symbolic link targets.
+
+@item S
+Do not apply transformation to symbolic link targets.
+
+@item h
+Apply transformation to hard link targets.
+
+@item H
+Do not apply transformation to hard link targets.
+@end table
+
+Default is @samp{rsh}, which means to apply tranformations to both archive
+members and targets of symbolic and hard links.
+
+Default scope flags can also be changed using @samp{flags=} statement
+in the transform expression. The flags set this way remain in force
+until next @samp{flags=} statement or end of expression, whichever
+occurs first. For example:
@smallexample
-@group
-s/one/two/
-s,one,two,
-@end group
+ --transform 'flags=S;s|^|/usr/local/|'
@end smallexample
-Changing delimiters is often useful when the @var{regex} contains
-slashes. For example, it is more convenient to write @code{s,/,-,} than
-@code{s/\//-/}.
-
Here are several examples of @option{--transform} usage:
@enumerate
$ @kbd{tar --transform='s,/*[^/]*/[^/]*/,,' -x -f arch.tar}
@end smallexample
+@item Convert each file name to lower case:
+
+@smallexample
+$ @kbd{tar --transform 's/.*/\L&/' -x -f arch.tar}
+@end smallexample
+
@item Prepend @file{/prefix/} to each file name:
@smallexample
$ @kbd{tar --transform 's,^,/prefix/,' -x -f arch.tar}
@end smallexample
-@item Convert each file name to lower case:
+@item Archive the @file{/lib} directory, prepending @samp{/usr/local}
+to each archive member:
@smallexample
-$ @kbd{tar --transform 's/.*/\L&/' -x -f arch.tar}
+$ @kbd{tar --transform 's,^,/usr/local/,S' -c -f arch.tar /lib}
@end smallexample
-
@end enumerate
+Notice the use of flags in the last example. The @file{/lib}
+directory often contains many symbolic links to files within it.
+It may look, for example, like this:
+
+@smallexample
+$ @kbd{ls -l}
+drwxr-xr-x root/root 0 2008-07-08 16:20 /lib/
+-rwxr-xr-x root/root 1250840 2008-05-25 07:44 /lib/libc-2.3.2.so
+lrwxrwxrwx root/root 0 2008-06-24 17:12 /lib/libc.so.6 -> libc-2.3.2.so
+...
+@end smallexample
+
+Using the expression @samp{s,^,/usr/local/,} would mean adding
+@samp{/usr/local} to both regular archive members and to link
+targets. In this case, @file{/lib/libc.so.6} would become:
+
+@smallexample
+ /usr/local/lib/libc.so.6 -> /usr/local/libc-2.3.2.so
+@end smallexample
+
+This is definitely not desired. To avoid this, the @samp{S} flag
+is used, which excludes symbolic link targets from filename
+transformations. The result is:
+
+@smallexample
+$ @kbd{tar --transform 's,^,/usr/local/,S', -c -v -f arch.tar \
+ --show-transformed /lib}
+drwxr-xr-x root/root 0 2008-07-08 16:20 /usr/local/lib/
+-rwxr-xr-x root/root 1250840 2008-05-25 07:44 /usr/local/lib/libc-2.3.2.so
+lrwxrwxrwx root/root 0 2008-06-24 17:12 /usr/local/lib/libc.so.6 \
+ -> libc-2.3.2.so
+@end smallexample
+
Unlike @option{--strip-components}, @option{--transform} can be used
in any @GNUTAR{} operation mode. For example, the following command
adds files to the archive while replacing the leading @file{usr/}
together, then @option{--transform} is applied first, and the required
number of components is then stripped from its result.
+You can use as many @option{--transform} options in a single command
+line as you want. The specified expressions will then be applied in
+order of their appearance. For example, the following two invocations
+are equivalent:
+
+@smallexample
+$ @kbd{tar -cf arch.tar --transform='s,/usr/var,/var/' \
+ --transform='s,/usr/local,/usr/,'}
+$ @kbd{tar -cf arch.tar \
+ --transform='s,/usr/var,/var/;s,/usr/local,/usr/,'}
+@end smallexample
+
@node after
@section Operating Only on New Files
-@UNREVISED
@cindex Excluding file by age
@cindex Data Modification time, excluding files by
modification of the file's data (rather than status
changes), then use the @option{--newer-mtime=@var{date}} option.
+@cindex --after-date and --update compared
+@cindex --newer-mtime and --update compared
You may use these options with any operation. Note that these options
differ from the @option{--update} (@option{-u}) operation in that they
allow you to specify a particular date against which @command{tar} can
@smallexample
@group
$ @kbd{tar -c -f archive.tar --after-date='10 days ago' .}
-tar: Option --after-date: Treating date `10 days ago' as 2006-06-11
+tar: Option --after-date: Treating date '10 days ago' as 2006-06-11
13:19:37.232434
@end group
@end smallexample
@node recurse
@section Descending into Directories
-@UNREVISED
@cindex Avoiding recursion in directories
@cindex Descending directories, avoiding
@cindex Directories, avoiding recursion
@cindex Recursion in directories, avoiding
-@FIXME{arrggh! this is still somewhat confusing to me. :-< }
-
Usually, @command{tar} will recursively explore all directories (either
those given on the command line or through the @option{--files-from}
option) for the various files they contain. However, you may not always
want @command{tar} to act this way.
@opindex no-recursion
+@cindex @command{find}, using with @command{tar}
The @option{--no-recursion} option inhibits @command{tar}'s recursive descent
into specified directories. If you specify @option{--no-recursion}, you can
-use the @command{find} utility for hunting through levels of directories to
+use the @command{find} (@pxref{Top,, find, find, GNU Find Manual})
+utility for hunting through levels of directories to
construct a list of file names which you could then pass to @command{tar}.
@command{find} allows you to be more selective when choosing which files to
archive; see @ref{files}, for more information on using @command{find} with
-@command{tar}, or look.
+@command{tar}.
@table @option
@item --no-recursion
@node one
@section Crossing File System Boundaries
@cindex File system boundaries, not crossing
-@UNREVISED
@command{tar} will normally automatically cross file system boundaries in
order to archive files which are part of a directory tree. You can
which records the third file in the archive under the name
@file{red/cherry} so that, if the archive is extracted using
@samp{tar --extract}, the third file will be written in a subdirectory
-named @file{orange-colored}.
+named @file{red}.
You can use the @option{--directory} option to make the archive
independent of the original name of the directory holding the files.
@node absolute
@subsection Absolute File Names
-@UNREVISED
+@cindex absolute file names
+@cindex file names, absolute
+
+By default, @GNUTAR{} drops a leading @samp{/} on
+input or output, and complains about file names containing a @file{..}
+component. There is an option that turns off this behavior:
@table @option
@opindex absolute-names
containing a @file{..} file name component.
@end table
-By default, @GNUTAR{} drops a leading @samp{/} on
-input or output, and complains about file names containing a @file{..}
-component. This option turns off this behavior.
-
When @command{tar} extracts archive members from an archive, it strips any
leading slashes (@samp{/}) from the member name. This causes absolute
member names in the archive to be treated as relative file names. This
leading slashes from member names when putting members into the
archive. For example, if you ask @command{tar} to add the file
@file{/bin/ls} to an archive, it will do so, but the member name will
-be @file{bin/ls}.@footnote{A side effect of this is that when
+be @file{bin/ls}@footnote{A side effect of this is that when
@option{--create} is used with @option{--verbose} the resulting output
is not, generally speaking, the same as the one you'd get running
@kbd{tar --list} command. This may be important if you use some
scripts for comparing both outputs. @xref{listing member and file names},
-for the information on how to handle this case.}
+for the information on how to handle this case.}.
+
+Symbolic links containing @file{..} or leading @samp{/} can also cause
+problems when extracting, so @command{tar} normally extracts them last;
+it may create empty files as placeholders during extraction.
If you use the @option{--absolute-names} (@option{-P}) option,
@command{tar} will do none of these transformations.
@FIXME{Should be an example in the tutorial/wizardry section using this
to transfer files between systems.}
-@FIXME{Is write access an issue?}
-
@table @option
@item --absolute-names
Preserves full file names (including superior directory names) when
-archiving files. Preserves leading slash when extracting files.
+archiving and extracting files.
@end table
-@FIXME{this is still horrible; need to talk with dan on monday.}
-
@command{tar} prints out a message about removing the @samp{/} from
file names. This message appears once per @GNUTAR{}
invocation. It represents something which ought to be told; ignoring
For example:
@smallexample
-$ @kbd{(cd / && tar -c -f archive.tar home)}
-# @i{or}:
-$ @kbd{tar -c -f archive.tar -C / home}
+$ @kbd{tar -c -f archive.tar -C / home}
@end smallexample
-@include getdate.texi
+@xref{Integrity}, for some of the security-related implications
+of using this option.
+
+@include parse-datetime.texi
@node Formats
@chapter Controlling the Archive Format
@cindex Compressed archives
@cindex Storing archives in compressed format
+@cindex gzip
+@cindex bzip2
+@cindex lzip
+@cindex lzma
+@cindex lzop
+@cindex compress
@GNUTAR{} is able to create and read compressed archives. It supports
-@command{gzip}, @command{bzip2} and @command{lzma} compression
-programs. For backward compatibility, it also supports
-@command{compress} command, although we strongly recommend against
-using it, since there is a patent covering the algorithm it uses and
-you could be sued for patent infringement merely by running
-@command{compress}! Besides, it is by far less effective than other
-compression programs.
+a wide variety of compression programs, namely: @command{gzip},
+@command{bzip2}, @command{lzip}, @command{lzma}, @command{lzop},
+@command{xz} and traditional @command{compress}. The latter is
+supported mostly for backward compatibility, and we recommend
+against using it, because it is by far less effective than the other
+compression programs@footnote{It also had patent problems in the past.}.
Creating a compressed archive is simple: you just specify a
@dfn{compression option} along with the usual archive creation
commands. The compression option is @option{-z} (@option{--gzip}) to
create a @command{gzip} compressed archive, @option{-j}
(@option{--bzip2}) to create a @command{bzip2} compressed archive,
-@command{lzma} to create an @asis{LZMA} compressed archive and
+@option{--lzip} to create an @asis{lzip} compressed archive,
+@option{-J} (@option{--xz}) to create an @asis{XZ} archive,
+@option{--lzma} to create an @asis{LZMA} compressed
+archive, @option{--lzop} to create an @asis{LSOP} archive, and
@option{-Z} (@option{--compress}) to use @command{compress} program.
For example:
@smallexample
-$ @kbd{tar cfz archive.tar.gz .}
+$ @kbd{tar czf archive.tar.gz .}
@end smallexample
-You can also let @GNUTAR{} select the compression program basing on
+You can also let @GNUTAR{} select the compression program based on
the suffix of the archive file name. This is done using
@option{--auto-compress} (@option{-a}) command line option. For
example, the following invocation will use @command{bzip2} for
compression:
@smallexample
-$ @kbd{tar cfa archive.tar.bz2 .}
+$ @kbd{tar caf archive.tar.bz2 .}
@end smallexample
@noindent
whereas the following one will use @command{lzma}:
@smallexample
-$ @kbd{tar cfa archive.tar.lzma .}
+$ @kbd{tar caf archive.tar.lzma .}
@end smallexample
For a complete list of file name suffixes recognized by @GNUTAR{},
-@ref{auto-compress}.
+see @ref{auto-compress}.
Reading compressed archive is even simpler: you don't need to specify
any additional options as @GNUTAR{} recognizes its format
$ @kbd{tar xf archive.tar.gz}
@end smallexample
+The format recognition algorithm is based on @dfn{signatures}, a
+special byte sequences in the beginning of file, that are specific for
+certain compression formats. If this approach fails, @command{tar}
+falls back to using archive name suffix to determine its format
+(@pxref{auto-compress}, for a list of recognized suffixes).
+
+@anchor{alternative decompression programs}
+@cindex alternative decompression programs
+Some compression programs are able to handle different compression
+formats. @GNUTAR{} uses this, if the principal decompressor for the
+given format is not available. For example, if @command{compress} is
+not installed, @command{tar} will try to use @command{gzip}. As of
+version @value{VERSION} the following alternatives are
+tried@footnote{To verbosely trace the decompressor selection, use the
+@option{--warning=decompress-program} option
+(@pxref{warnings,decompress-program}).}:
+
+@multitable @columnfractions 0.3 0.3 0.3
+@headitem Format @tab Main decompressor @tab Alternatives
+@item compress @tab compress @tab gzip
+@item lzma @tab lzma @tab xz
+@item bzip2 @tab bzip2 @tab lbzip2
+@end multitable
+
The only case when you have to specify a decompression option while
reading the archive is when reading from a pipe or from a tape drive
that does not support random access. However, in this case @GNUTAR{}
invocation of @GNUTAR{}:
@smallexample
-$ @kbd{cat archive.tar.gz | tar tfz -}
+$ @kbd{cat archive.tar.gz | tar tzf -}
@end smallexample
Notice also, that there are several restrictions on operations on
compressed archives. First of all, compressed archives cannot be
-modified, i.e., you cannot update (@option{--update} (@option{-u})) them or delete
-(@option{--delete}) members from them. Likewise, you cannot append
-another @command{tar} archive to a compressed archive using
-@option{--append} (@option{-r})). Secondly, multi-volume archives cannot be
-compressed.
+modified, i.e., you cannot update (@option{--update}, alias @option{-u})
+them or delete (@option{--delete}) members from them or
+add (@option{--append}, alias @option{-r}) members to them. Likewise, you
+cannot append another @command{tar} archive to a compressed archive using
+@option{--concatenate} (@option{-A}). Secondly, multi-volume
+archives cannot be compressed.
-The following table summarizes compression options used by @GNUTAR{}.
+The following options allow to select a particular compressor program:
@table @option
-@anchor{auto-compress}
-@opindex auto-compress
-@item --auto-compress
-@itemx -a
-Select a compression program to use by the archive file name
-suffix. The following suffixes are recognized:
-
-@multitable @columnfractions 0.3 0.6
-@headitem Suffix @tab Compression program
-@item @samp{.gz} @tab @command{gzip}
-@item @samp{.tgz} @tab @command{gzip}
-@item @samp{.taz} @tab @command{gzip}
-@item @samp{.Z} @tab @command{compress}
-@item @samp{.taZ} @tab @command{compress}
-@item @samp{.bz2} @tab @command{bzip2}
-@item @samp{.tz2} @tab @command{bzip2}
-@item @samp{.tbz2} @tab @command{bzip2}
-@item @samp{.tbz} @tab @command{bzip2}
-@item @samp{.lzma} @tab @command{lzma}
-@item @samp{.tlz} @tab @command{lzma}
-@end multitable
-
@opindex gzip
@opindex ungzip
@item -z
@itemx --ungzip
Filter the archive through @command{gzip}.
-You can use @option{--gzip} and @option{--gunzip} on physical devices
-(tape drives, etc.) and remote files as well as on normal files; data
-to or from such devices or remote files is reblocked by another copy
-of the @command{tar} program to enforce the specified (or default) record
-size. The default compression parameters are used; if you need to
-override them, set @env{GZIP} environment variable, e.g.:
+@opindex xz
+@item -J
+@itemx --xz
+Filter the archive through @code{xz}.
+
+@item -j
+@itemx --bzip2
+Filter the archive through @code{bzip2}.
+
+@opindex lzip
+@item --lzip
+Filter the archive through @command{lzip}.
+
+@opindex lzma
+@item --lzma
+Filter the archive through @command{lzma}.
+
+@opindex lzop
+@item --lzop
+Filter the archive through @command{lzop}.
+
+@opindex compress
+@opindex uncompress
+@item -Z
+@itemx --compress
+@itemx --uncompress
+Filter the archive through @command{compress}.
+@end table
+
+When any of these options is given, @GNUTAR{} searches the compressor
+binary in the current path and invokes it. The name of the compressor
+program is specified at compilation time using a corresponding
+@option{--with-@var{compname}} option to @command{configure}, e.g.
+@option{--with-bzip2} to select a specific @command{bzip2} binary.
+@xref{lbzip2}, for a detailed discussion.
+
+The output produced by @command{tar --help} shows the actual
+compressor names along with each of these options.
+
+You can use any of these options on physical devices (tape drives,
+etc.) and remote files as well as on normal files; data to or from
+such devices or remote files is reblocked by another copy of the
+@command{tar} program to enforce the specified (or default) record
+size. The default compression parameters are used. Most compression
+programs let you override these by setting a program-specific
+environment variable. For example, with @command{gzip} you can set
+@env{GZIP}:
@smallexample
-$ @kbd{GZIP=--best tar cfz archive.tar.gz subdir}
+$ @kbd{GZIP='-9 -n' tar czf archive.tar.gz subdir}
+@end smallexample
+Another way would be to use the @option{-I} option instead (see
+below), e.g.:
+
+@smallexample
+$ @kbd{tar -cf archive.tar.gz -I 'gzip -9 -n' subdir}
@end smallexample
@noindent
-Another way would be to avoid the @option{--gzip} (@option{--gunzip}, @option{--ungzip}, @option{-z}) option and run
-@command{gzip} explicitly:
+Finally, the third, traditional, way to do this is to use a pipe:
@smallexample
-$ @kbd{tar cf - subdir | gzip --best -c - > archive.tar.gz}
+$ @kbd{tar cf - subdir | gzip -9 -n > archive.tar.gz}
@end smallexample
@cindex corrupted archives
-About corrupted compressed archives: @command{gzip}'ed files have no
-redundancy, for maximum compression. The adaptive nature of the
+Compressed archives are easily corrupted, because compressed files
+have little redundancy. The adaptive nature of the
compression scheme means that the compression tables are implicitly
spread all over the archive. If you lose a few blocks, the dynamic
construction of the compression tables becomes unsynchronized, and there
is little chance that you could recover later in the archive.
-There are pending suggestions for having a per-volume or per-file
-compression in @GNUTAR{}. This would allow for viewing the
-contents without decompression, and for resynchronizing decompression at
-every volume or file, in case of corrupted archives. Doing so, we might
-lose some compressibility. But this would have make recovering easier.
-So, there are pros and cons. We'll see!
+Other compression options provide better control over creating
+compressed archives. These are:
-@opindex bzip2
-@item -j
-@itemx --bzip2
-Filter the archive through @code{bzip2}. Otherwise like @option{--gzip}.
-
-@opindex lzma
-@item --lzma
-Filter the archive through @command{lzma}. Otherwise like @option{--gzip}.
-
-@opindex compress
-@opindex uncompress
-@item -Z
-@itemx --compress
-@itemx --uncompress
-Filter the archive through @command{compress}. Otherwise like @option{--gzip}.
+@table @option
+@anchor{auto-compress}
+@opindex auto-compress
+@item --auto-compress
+@itemx -a
+Select a compression program to use by the archive file name
+suffix. The following suffixes are recognized:
-The @acronym{GNU} Project recommends you not use
-@command{compress}, because there is a patent covering the algorithm it
-uses. You could be sued for patent infringement merely by running
-@command{compress}.
+@multitable @columnfractions 0.3 0.6
+@headitem Suffix @tab Compression program
+@item @samp{.gz} @tab @command{gzip}
+@item @samp{.tgz} @tab @command{gzip}
+@item @samp{.taz} @tab @command{gzip}
+@item @samp{.Z} @tab @command{compress}
+@item @samp{.taZ} @tab @command{compress}
+@item @samp{.bz2} @tab @command{bzip2}
+@item @samp{.tz2} @tab @command{bzip2}
+@item @samp{.tbz2} @tab @command{bzip2}
+@item @samp{.tbz} @tab @command{bzip2}
+@item @samp{.lz} @tab @command{lzip}
+@item @samp{.lzma} @tab @command{lzma}
+@item @samp{.tlz} @tab @command{lzma}
+@item @samp{.lzo} @tab @command{lzop}
+@item @samp{.xz} @tab @command{xz}
+@end multitable
+@anchor{use-compress-program}
@opindex use-compress-program
-@item --use-compress-program=@var{prog}
-Use external compression program @var{prog}. Use this option if you
-have a compression program that @GNUTAR{} does not support. There
-are two requirements to which @var{prog} should comply:
-
-First, when called without options, it should read data from standard
-input, compress it and output it on standard output.
-
-Secondly, if called with @option{-d} argument, it should do exactly
-the opposite, i.e., read the compressed data from the standard input
-and produce uncompressed data on the standard output.
+@item --use-compress-program=@var{command}
+@itemx -I=@var{command}
+Use external compression program @var{command}. Use this option if you
+are not happy with the compression program associated with the suffix
+at compile time or if you have a compression program that @GNUTAR{}
+does not support. The @var{command} argument is a valid command
+invocation, as you would type it at the command line prompt, with any
+additional options as needed. Enclose it in quotes if it contains
+white space (see @ref{external, Running External Commands}, for more detail).
+
+The @var{command} should follow two conventions:
+
+First, when invoked without additional options, it should read data
+from standard input, compress it and output it on standard output.
+
+Secondly, if invoked with the additional @option{-d} option, it should
+do exactly the opposite, i.e., read the compressed data from the
+standard input and produce uncompressed data on the standard output.
+
+The latter requirement means that you must not use the @option{-d}
+option as a part of the @var{command} itself.
@end table
@cindex gpg, using with tar
#! /bin/sh
case $1 in
-d) gpg --decrypt - | gzip -d -c;;
-'') gzip -c | gpg -s ;;
+'') gzip -c | gpg -s;;
*) echo "Unknown option $1">&2; exit 1;;
esac
@end group
archive signed with your private key:
@smallexample
-$ @kbd{tar -cf foo.tar.gpgz --use-compress=gpgz .}
+$ @kbd{tar -cf foo.tar.gpgz -Igpgz .}
@end smallexample
@noindent
-Likewise, the following command will list its contents:
+Likewise, the command below will list its contents:
@smallexample
-$ @kbd{tar -tf foo.tar.gpgz --use-compress=gpgz .}
+$ @kbd{tar -tf foo.tar.gpgz -Igpgz .}
@end smallexample
@ignore
end up with less space on the tape.
@end ignore
+@menu
+* lbzip2:: Using lbzip2 with @GNUTAR{}.
+@end menu
+
+@node lbzip2
+@subsubsection Using lbzip2 with @GNUTAR{}.
+@cindex lbzip2
+@cindex Laszlo Ersek
+ @command{Lbzip2} is a multithreaded utility for handling
+@samp{bzip2} compression, written by Laszlo Ersek. It makes use of
+multiple processors to speed up its operation and in general works
+considerably faster than @command{bzip2}. For a detailed description
+of @command{lbzip2} see @uref{http://freshmeat.net/@/projects/@/lbzip2} and
+@uref{http://www.linuxinsight.com/@/lbzip2-parallel-bzip2-utility.html,
+lbzip2: parallel bzip2 utility}.
+
+ Recent versions of @command{lbzip2} are mostly command line compatible
+with @command{bzip2}, which makes it possible to automatically invoke
+it via the @option{--bzip2} @GNUTAR{} command line option. To do so,
+@GNUTAR{} must be configured with the @option{--with-bzip2} command
+line option, like this:
+
+@smallexample
+$ @kbd{./configure --with-bzip2=lbzip2 [@var{other-options}]}
+@end smallexample
+
+ Once configured and compiled this way, @command{tar --help} will show the
+following:
+
+@smallexample
+@group
+$ @kbd{tar --help | grep -- --bzip2}
+ -j, --bzip2 filter the archive through lbzip2
+@end group
+@end smallexample
+
+@noindent
+which means that running @command{tar --bzip2} will invoke @command{lbzip2}.
+
@node sparse
@subsection Archiving Sparse Files
@cindex Sparse Files
@node Attributes
@section Handling File Attributes
-@UNREVISED
+@cindex atrributes, files
+@cindex file attributes
When @command{tar} reads files, it updates their access times. To
avoid this, use the @option{--atime-preserve[=METHOD]} option, which can either
reset the access time retroactively or avoid changing it in the first
place.
-Handling of file attributes
-
@table @option
@opindex atime-preserve
@item --atime-preserve
The numeric ids are @emph{always} saved into @command{tar} archives.
The identifying names are added at create time when provided by the
-system, unless @option{--old-archive} (@option{-o}) is used. Numeric ids could be
+system, unless @option{--format=oldgnu} is used. Numeric ids could be
used when moving archives between a collection of machines using
a centralized management for attribution of numeric ids to users
and groups. This is often made through using the NIS capabilities.
@item --preserve
Same as both @option{--same-permissions} and @option{--same-order}.
-The @option{--preserve} option has no equivalent short option name.
-It is equivalent to @option{--same-permissions} plus @option{--same-order}.
-
-@FIXME{I do not see the purpose of such an option. (Neither I. FP.)
-Neither do I. --Sergey}
+This option is deprecated, and will be removed in @GNUTAR{} version 1.23.
@end table
@menu
* Portable Names:: Portable Names
* dereference:: Symbolic Links
+* hard links:: Hard Links
* old:: Old V7 Archives
* ustar:: Ustar Archives
* gnu:: GNU and old GNU format archives.
Normally, when @command{tar} archives a symbolic link, it writes a
block to the archive naming the target of the link. In that way, the
@command{tar} archive is a faithful record of the file system contents.
-@option{--dereference} (@option{-h}) is used with @option{--create} (@option{-c}), and causes
-@command{tar} to archive the files symbolic links point to, instead of
-the links themselves. When this option is used, when @command{tar}
-encounters a symbolic link, it will archive the linked-to file,
-instead of simply recording the presence of a symbolic link.
-
-The name under which the file is stored in the file system is not
-recorded in the archive. To record both the symbolic link name and
-the file name in the system, archive the file under both names. If
-all links were recorded automatically by @command{tar}, an extracted file
-might be linked to a file name that no longer exists in the file
-system.
+When @option{--dereference} (@option{-h}) is used with
+@option{--create} (@option{-c}), @command{tar} archives the files
+symbolic links point to, instead of
+the links themselves.
-If a linked-to file is encountered again by @command{tar} while creating
-the same archive, an entire second copy of it will be stored. (This
-@emph{might} be considered a bug.)
-
-So, for portable archives, do not archive symbolic links as such,
-and use @option{--dereference} (@option{-h}): many systems do not support
+When creating portable archives, use @option{--dereference}
+(@option{-h}): some systems do not support
symbolic links, and moreover, your distribution might be unusable if
it contains unresolved symbolic links.
+When reading from an archive, the @option{--dereference} (@option{-h})
+option causes @command{tar} to follow an already-existing symbolic
+link when @command{tar} writes or reads a file named in the archive.
+Ordinarily, @command{tar} does not follow such a link, though it may
+remove the link before writing a new file. @xref{Dealing with Old
+Files}.
+
+The @option{--dereference} option is unsafe if an untrusted user can
+modify directories while @command{tar} is running. @xref{Security}.
+
+@node hard links
+@subsection Hard Links
+@cindex File names, using hard links
+@cindex hard links, dereferencing
+@cindex dereferencing hard links
+
+Normally, when @command{tar} archives a hard link, it writes a
+block to the archive naming the target of the link (a @samp{1} type
+block). In that way, the actual file contents is stored in file only
+once. For example, consider the following two files:
+
+@smallexample
+@group
+$ ls -l
+-rw-r--r-- 2 gray staff 4 2007-10-30 15:11 one
+-rw-r--r-- 2 gray staff 4 2007-10-30 15:11 jeden
+@end group
+@end smallexample
+
+Here, @file{jeden} is a link to @file{one}. When archiving this
+directory with a verbose level 2, you will get an output similar to
+the following:
+
+@smallexample
+$ tar cvvf ../archive.tar .
+drwxr-xr-x gray/staff 0 2007-10-30 15:13 ./
+-rw-r--r-- gray/staff 4 2007-10-30 15:11 ./jeden
+hrw-r--r-- gray/staff 0 2007-10-30 15:11 ./one link to ./jeden
+@end smallexample
+
+The last line shows that, instead of storing two copies of the file,
+@command{tar} stored it only once, under the name @file{jeden}, and
+stored file @file{one} as a hard link to this file.
+
+It may be important to know that all hard links to the given file are
+stored in the archive. For example, this may be necessary for exact
+reproduction of the file system. The following option does that:
+
+@table @option
+@xopindex{check-links, described}
+@item --check-links
+@itemx -l
+Check the number of links dumped for each processed file. If this
+number does not match the total number of hard links for the file, print
+a warning message.
+@end table
+
+For example, trying to archive only file @file{jeden} with this option
+produces the following diagnostics:
+
+@smallexample
+$ tar -c -f ../archive.tar -l jeden
+tar: Missing links to 'jeden'.
+@end smallexample
+
+Although creating special records for hard links helps keep a faithful
+record of the file system contents and makes archives more compact, it
+may present some difficulties when extracting individual members from
+the archive. For example, trying to extract file @file{one} from the
+archive created in previous examples produces, in the absense of file
+@file{jeden}:
+
+@smallexample
+$ tar xf archive.tar ./one
+tar: ./one: Cannot hard link to './jeden': No such file or directory
+tar: Error exit delayed from previous errors
+@end smallexample
+
+The reason for this behavior is that @command{tar} cannot seek back in
+the archive to the previous member (in this case, @file{one}), to
+extract it@footnote{There are plans to fix this in future releases.}.
+If you wish to avoid such problems at the cost of a bigger archive,
+use the following option:
+
+@table @option
+@xopindex{hard-dereference, described}
+@item --hard-dereference
+Dereference hard links and store the files they refer to.
+@end table
+
+For example, trying this option on our two sample files, we get two
+copies in the archive, each of which can then be extracted
+independently of the other:
+
+@smallexample
+@group
+$ tar -c -vv -f ../archive.tar --hard-dereference .
+drwxr-xr-x gray/staff 0 2007-10-30 15:13 ./
+-rw-r--r-- gray/staff 4 2007-10-30 15:11 ./jeden
+-rw-r--r-- gray/staff 4 2007-10-30 15:11 ./one
+@end group
+@end smallexample
+
@node old
@subsection Old V7 Archives
@cindex Format, old style
@cindex ustar archive format
Archive format defined by @acronym{POSIX}.1-1988 specification is called
@code{ustar}. Although it is more flexible than the V7 format, it
-still has many restrictions (@xref{Formats,ustar}, for the detailed
+still has many restrictions (@pxref{Formats,ustar}, for the detailed
description of @code{ustar} format). Along with V7 format,
@code{ustar} format is a good choice for archives intended to be read
with other implementations of @command{tar}.
result of the @command{dirname} utility on the translated file name.
@item %f @tab The name of the file with the directory information
stripped, equivalent to the result of the @command{basename} utility
-on the translated file name.
+on the translated file name.
@item %p @tab The process @acronym{ID} of the @command{tar} process.
@item %% @tab A @samp{%} character.
@end multitable
%d/PaxHeaders.%p/%f
@end smallexample
+@item exthdr.mtime=@var{value}
+
+This keyword defines the value of the @samp{mtime} field that
+is written into the ustar header blocks for the extended headers.
+By default, the @samp{mtime} field is set to the modification time
+of the archive member described by that extended headers.
+
@item globexthdr.name=@var{string}
This keyword allows user control over the name that is written into
the ustar header blocks for global extended header records. The name
environment variable. If @var{TMPDIR} is not set, @command{tar}
uses @samp{/tmp}.
+@item globexthdr.mtime=@var{value}
+
+This keyword defines the value of the @samp{mtime} field that
+is written into the ustar header blocks for the global extended headers.
+By default, the @samp{mtime} field is set to the time when
+@command{tar} was invoked.
+
@item @var{keyword}=@var{value}
When used with one of archive-creation commands, these keyword/value pairs
will be included at the beginning of the archive in a global extended
stored in the archive.
@end table
+In any of the forms described above, the @var{value} may be
+a string enclosed in curly braces. In that case, the string
+between the braces is understood either as a textual time
+representation, as described in @ref{Date input formats}, or a name of
+the existing file, starting with @samp{/} or @samp{.}. In the latter
+case, the modification time of that file is used.
+
+For example, to set all modification times to the current date, you
+use the following option:
+
+@smallexample
+--pax-option='mtime:=@{now@}'
+@end smallexample
+
+Note quoting of the option's argument.
+
+@cindex archives, binary equivalent
+@cindex binary equivalent archives, creating
+As another example, here is the option that ensures that any two
+archives created using it, will be binary equivalent if they have the
+same contents:
+
+@smallexample
+--pax-option=exthdr.name=%d/PaxHeaders/%f,atime:=0
+@end smallexample
+
@node Checksumming
@subsection Checksumming Problems
use signed checksums, while @GNUTAR{} uses unsigned
checksums while creating archives, as per @acronym{POSIX} standards. On
reading, @GNUTAR{} computes both checksums and
-accept any. It is somewhat worrying that a lot of people may go
+accepts any. It is somewhat worrying that a lot of people may go
around doing backup of their files using faulty (or at least
non-standard) software, not learning about it until it's time to
restore their missing files with an incompatible file extractor, or
vice versa.
-@GNUTAR{} compute checksums both ways, and accept
+@GNUTAR{} computes checksums both ways, and accept
any on read, so @acronym{GNU} tar can read Sun tapes even with their
wrong checksums. @GNUTAR{} produces the standard
checksum, however, raising incompatibilities with Sun. That is to
@cindex large values
@cindex future time stamps
@cindex negative time stamps
-@UNREVISED{}
+@UNREVISED
The above sections suggest to use @samp{oldest possible} archive
format if in doubt. However, sometimes it is not possible. If you
additional data will be needed to restore it. If the original file
name was @file{@var{dir}/@var{name}}, then the condensed file will be
named @file{@var{dir}/@/GNUSparseFile.@var{n}/@/@var{name}}, where
-@var{n} is a decimal number@footnote{technically speaking, @var{n} is a
+@var{n} is a decimal number@footnote{Technically speaking, @var{n} is a
@dfn{process @acronym{ID}} of the @command{tar} process which created the
archive (@pxref{PAX keywords}).}.
@group
$ @kbd{xsparse -n /home/gray/GNUSparseFile.6058/sparsefile}
Reading v.1.0 sparse map
-Expanding file `/home/gray/GNUSparseFile.6058/sparsefile' to
-`/home/gray/sparsefile'
+Expanding file '/home/gray/GNUSparseFile.6058/sparsefile' to
+'/home/gray/sparsefile'
Finished dry run
@end group
@end smallexample
@group
$ @kbd{xsparse -v /home/gray/GNUSparseFile.6058/sparsefile}
Reading v.1.0 sparse map
-Expanding file `/home/gray/GNUSparseFile.6058/sparsefile' to
-`/home/gray/sparsefile'
+Expanding file '/home/gray/GNUSparseFile.6058/sparsefile' to
+'/home/gray/sparsefile'
Done
@end group
@end smallexample
Found variable GNU.sparse.name = sparsefile
Found variable GNU.sparse.realsize = 217481216
Reading v.1.0 sparse map
-Expanding file `/home/gray/GNUSparseFile.6058/sparsefile' to
-`/home/gray/sparsefile'
+Expanding file '/home/gray/GNUSparseFile.6058/sparsefile' to
+'/home/gray/sparsefile'
Done
@end group
@end smallexample
Found variable GNU.sparse.numblocks = 208
Found variable GNU.sparse.name = sparsefile
Found variable GNU.sparse.map = 0,2048,1050624,2048,@dots{}
-Expanding file `GNUSparseFile.28124/sparsefile' to `sparsefile'
+Expanding file 'GNUSparseFile.28124/sparsefile' to 'sparsefile'
Done
@end group
@end smallexample
(4.3-tahoe and later).
@command{tar}'s way of handling multiple hard links to a file can handle
-file systems that support 32-bit inumbers (e.g., the @acronym{BSD} file system);
+file systems that support 32-bit i-numbers (e.g., the @acronym{BSD} file system);
@command{cpio}s way requires you to play some games (in its ``binary''
format, i-numbers are only 16 bits, and in its ``portable @acronym{ASCII}'' format,
they're 18 bits---it would have to play games with the "file system @acronym{ID}"
The exact path to this utility is determined when configuring the package.
It is @file{@var{prefix}/libexec/rmt}, where @var{prefix} stands for
your installation prefix. This location may also be overridden at
-runtime by using @option{rmt-command=@var{command}} option (@xref{Option Summary,
+runtime by using the @option{--rmt-command=@var{command}} option (@xref{Option Summary,
---rmt-command}, for detailed description of this option. @xref{Remote
Tape Server}, for the description of @command{rmt} command).
@xopindex{tape-length, short description}
@item -L @var{num}
-@itemx --tape-length=@var{num}
-Change tape after writing @var{num} x 1024 bytes.
+@itemx --tape-length=@var{size}[@var{suf}]
+Change tape after writing @var{size} units of data. Unless @var{suf} is
+given, @var{size} is treated as kilobytes, i.e. @samp{@var{size} x
+1024} bytes. The following suffixes alter this behavior:
+
+@float Table, size-suffixes
+@caption{Size Suffixes}
+@multitable @columnfractions 0.2 0.3 0.3
+@headitem Suffix @tab Units @tab Byte Equivalent
+@item b @tab Blocks @tab @var{size} x 512
+@item B @tab Kilobytes @tab @var{size} x 1024
+@item c @tab Bytes @tab @var{size}
+@item G @tab Gigabytes @tab @var{size} x 1024^3
+@item K @tab Kilobytes @tab @var{size} x 1024
+@item k @tab Kilobytes @tab @var{size} x 1024
+@item M @tab Megabytes @tab @var{size} x 1024^2
+@item P @tab Petabytes @tab @var{size} x 1024^5
+@item T @tab Terabytes @tab @var{size} x 1024^4
+@item w @tab Words @tab @var{size} x 2
+@end multitable
+@end float
This option might be useful when your tape drivers do not properly
detect end of physical tapes. By being slightly conservative on the
@xopindex{info-script, short description}
@xopindex{new-volume-script, short description}
-@item -F @var{file}
-@itemx --info-script=@var{file}
-@itemx --new-volume-script=@var{file}
-Execute @file{file} at end of each tape. This implies
+@item -F @var{command}
+@itemx --info-script=@var{command}
+@itemx --new-volume-script=@var{command}
+Execute @var{command} at end of each tape. This implies
@option{--multi-volume} (@option{-M}). @xref{info-script}, for a detailed
description of this option.
@end table
@node Remote Tape Server
-@section The Remote Tape Server
+@section Remote Tape Server
@cindex remote tape drive
@pindex rmt
@command{rsh} or @command{remsh} to the remote machine, optionally
using a different login name if one is supplied.
-A copy of the source for the remote tape server is provided. It is
-Copyright @copyright{} 1983 by the Regents of the University of
-California, but can be freely distributed. It is compiled and
+A copy of the source for the remote tape server is provided. Its
+source code can be freely distributed. It is compiled and
installed by default.
@cindex absolute file names
written). This is currently possible only on two kinds of files: normal
disk files (or any other file that can be backspaced with @samp{lseek}),
and industry-standard 9-track magnetic tape (or any other kind of tape
-that can be backspaced with the @code{MTIOCTOP} @code{ioctl}.
+that can be backspaced with the @code{MTIOCTOP} @code{ioctl}).
This means that the @option{--append}, @option{--concatenate}, and
@option{--delete} commands will not work on any other kind of file.
@node Blocking
@section Blocking
-@UNREVISED
+@cindex block
+@cindex record
@dfn{Block} and @dfn{record} terminology is rather confused, and it
is also confusing to the expert reader. On the other hand, readers
record size on itself. When this is the case, and a non-standard
record size was used when the archive was created, @command{tar} will
print a message about a non-standard blocking factor, and then operate
-normally. On some tape devices, however, @command{tar} cannot figure
-out the record size itself. On most of those, you can specify a
-blocking factor (with @option{--blocking-factor}) larger than the
-actual blocking factor, and then use the @option{--read-full-records}
-(@option{-B}) option. (If you specify a blocking factor with
-@option{--blocking-factor} and don't use the
-@option{--read-full-records} option, then @command{tar} will not
-attempt to figure out the recording size itself.) On some devices,
-you must always specify the record size exactly with
+normally@footnote{If this message is not needed, you can turn it off
+using the @option{--warning=no-record-size} option.}. On some tape
+devices, however, @command{tar} cannot figure out the record size
+itself. On most of those, you can specify a blocking factor (with
+@option{--blocking-factor}) larger than the actual blocking factor,
+and then use the @option{--read-full-records} (@option{-B}) option.
+(If you specify a blocking factor with @option{--blocking-factor} and
+don't use the @option{--read-full-records} option, then @command{tar}
+will not attempt to figure out the recording size itself.) On some
+devices, you must always specify the record size exactly with
@option{--blocking-factor} when reading, because @command{tar} cannot
figure it out. In any case, use @option{--list} (@option{-t}) before
doing any extractions to see whether @command{tar} is reading the archive
blocking factor (particularly if you're not sure what the blocking factor
is), you can usually use the @option{--read-full-records} (@option{-B}) option while
specifying a blocking factor larger then the blocking factor of the archive
-(i.e., @samp{tar --extract --read-full-records --blocking-factor=300}.
+(i.e., @samp{tar --extract --read-full-records --blocking-factor=300}).
@xref{list}, for more information on the @option{--list} (@option{-t})
operation. @xref{Reading}, for a more detailed explanation of that option.
@table @option
@item -b @var{blocks}
@itemx --blocking-factor=@var{blocks}
-Set record size to @math{@var{blocks} * 512} bytes.
+Set record size to @math{@var{blocks}*512} bytes.
This option is used to specify a @dfn{blocking factor} for the archive.
When reading or writing the archive, @command{tar}, will do reads and writes
full stop, and for later regaining the reading or writing speed.
When the tape driver starts reading a record, the record has to
be read whole without stopping, as a tape gap is needed to stop the
-tape motion without loosing information.
+tape motion without losing information.
@cindex Exabyte blocking
@cindex DAT blocking
Moves tape position back @var{number} files.
@item rewind
-Rewinds the tape. (Ignores @var{number}).
+Rewinds the tape. (Ignores @var{number}.)
@item offline
@itemx rewoff1
-Rewinds the tape and takes the tape device off-line. (Ignores @var{number}).
+Rewinds the tape and takes the tape device off-line. (Ignores @var{number}.)
@item status
Prints status information about the tape unit.
@end table
-@FIXME{Is there a better way to frob the spacing on the list?}
-
If you don't specify a @var{tapename}, @command{mt} uses the environment
variable @env{TAPE}; if @env{TAPE} is not set, @command{mt} will use
the default device specified in your @file{sys/mtio.h} file
the @option{--create} option (@pxref{create}). A @dfn{multi-volume}
archive can be manipulated like any other archive (provided the
@option{--multi-volume} option is specified), but is stored on more
-than one tape or disk.
+than one tape or file.
When you specify @option{--multi-volume}, @command{tar} does not report an
error when it comes to the end of an archive volume (when reading), or
@anchor{tape-length}
@table @option
@opindex tape-length
-@item --tape-length=@var{size}
-@itemx -L @var{size}
-Set maximum length of a volume. The @var{size} argument should then
-be the usable size of the tape in units of 1024 bytes. This option
-selects @option{--multi-volume} automatically. For example:
+@item --tape-length=@var{size}[@var{suf}]
+@itemx -L @var{size}[@var{suf}]
+Set maximum length of a volume. The @var{suf}, if given, specifies
+units in which @var{size} is expressed, e.g. @samp{2M} mean 2
+megabytes (@pxref{size-suffixes}, for a list of allowed size
+suffixes). Without @var{suf}, units of 1024 bytes (kilobyte) are
+assumed.
+
+This option selects @option{--multi-volume} automatically. For example:
@smallexample
$ @kbd{tar --create --tape-length=41943040 --file=/dev/tape @var{files}}
@end smallexample
+
+@noindent
+or, which is equivalent:
+
+@smallexample
+$ @kbd{tar --create --tape-length=4G --file=/dev/tape @var{files}}
+@end smallexample
@end table
@anchor{change volume prompt}
translation to the locale's language will be used.}:
@smallexample
-Prepare volume #@var{n} for `@var{archive}' and hit return:
+Prepare volume #@var{n} for '@var{archive}' and hit return:
@end smallexample
@noindent
@table @kbd
@item ?
-Request @command{tar} to explain possible responses
+Request @command{tar} to explain possible responses.
@item q
Request @command{tar} to exit immediately.
@item n @var{file-name}
Request @command{tar} to run a subshell. This option can be disabled
by giving @option{--restrict} command line option to
@command{tar}@footnote{@xref{--restrict}, for more information about
-this option}.
+this option.}.
@item y
Request @command{tar} to begin writing the next volume.
@end table
prompting procedure:
@table @option
-@item --info-script=@var{script-name}
-@itemx --new-volume-script=@var{script-name}
-@itemx -F @var{script-name}
-Specify the full name of the volume script to use. The script can be
-used to eject cassettes, or to broadcast messages such as
+@item --info-script=@var{command}
+@itemx --new-volume-script=@var{command}
+@itemx -F @var{command}
+Specify the command to invoke when switching volumes. The @var{command}
+can be used to eject cassettes, or to broadcast messages such as
@samp{Someone please come change my tape} when performing unattended
backups.
@end table
-The @var{script-name} is executed without any command line
-arguments. It inherits @command{tar}'s shell environment.
-Additional data is passed to it via the following
-environment variables:
+The @var{command} can contain additional options, if such are needed.
+@xref{external, Running External Commands}, for a detailed discussion
+of the way @GNUTAR{} runs external commands. It inherits
+@command{tar}'s shell environment. Additional data is passed to it
+via the following environment variables:
@table @env
@vrindex TAR_VERSION, info script environment variable
@item TAR_ARCHIVE
The name of the archive @command{tar} is processing.
+@vrindex TAR_BLOCKING_FACTOR, info script environment variable
+@item TAR_BLOCKING_FACTOR
+Current blocking factor (@pxref{Blocking}).
+
@vrindex TAR_VOLUME, info script environment variable
@item TAR_VOLUME
Ordinal number of the volume @command{tar} is about to start.
@vrindex TAR_SUBCOMMAND, info script environment variable
@item TAR_SUBCOMMAND
-Short option describing the operation @command{tar} is executing
+A short option describing the operation @command{tar} is executing.
@xref{Operations}, for a complete list of subcommand options.
@vrindex TAR_FORMAT, info script environment variable
name to @command{tar}.
@end table
+These variables can be used in the @var{command} itself, provided that
+they are properly quoted to prevent them from being expanded by the
+shell that invokes @command{tar}.
+
The volume script can instruct @command{tar} to use new archive name,
by writing in to file descriptor @env{$TAR_FD} (see below for an example).
@smallexample
$ @kbd{tar --create --multi-volume --file=/dev/tape0 --file=/dev/tape1 @var{files}}
-$ @kbd{tar cMff /dev/tape0 /dev/tape1 @var{files}}
+$ @kbd{tar -cM -f /dev/tape0 -f /dev/tape1 @var{files}}
@end smallexample
The second method is to use the @samp{n} response to the tape-change
@smallexample
@group
-#! /bin/sh
+#! /bin/bash
+# For this script it's advisable to use a shell, such as Bash,
+# that supports a TAR_FD value greater than 9.
+
echo Preparing volume $TAR_VOLUME of $TAR_ARCHIVE.
name=`expr $TAR_ARCHIVE : '\(.*\)-.*'`
case $TAR_SUBCOMMAND in
-c) ;;
-d|-x|-t) test -r $@{name:-$TAR_ARCHIVE@}-$TAR_VOLUME || exit 1
- ;;
+ ;;
*) exit 1
esac
@node Tape Files
@subsection Tape Files
+@cindex labeling archives
+@opindex label
@UNREVISED
To give the archive a name which will be recorded in it, use the
@option{--multi-volume} (@pxref{Using Multiple Tapes}), then the
volume label will have @samp{Volume @var{nnn}} appended to the name
you give, where @var{nnn} is the number of the volume of the archive.
-(If you use the @option{--label=@var{volume-label}}) option when
+If you use the @option{--label=@var{volume-label}} option when
reading an archive, it checks to make sure the label on the tape
-matches the one you give. @xref{label}.
+matches the one you gave. @xref{label}.
When @command{tar} writes an archive to tape, it creates a single
tape file. If multiple archives are written to the same tape, one
@cindex Labeling an archive
@cindex Labels on the archive media
@cindex Labeling multi-volume archives
-@UNREVISED
@opindex label
To avoid problems caused by misplaced paper labels on the archive
-media, you can include a @dfn{label} entry---an archive member which
-contains the name of the archive---in the archive itself. Use the
+media, you can include a @dfn{label} entry --- an archive member which
+contains the name of the archive --- in the archive itself. Use the
@option{--label=@var{archive-label}} (@option{-V @var{archive-label}})
-option in conjunction with the @option{--create} operation to include
-a label entry in the archive as it is being created.
+option@footnote{Until version 1.10, that option was called
+@option{--volume}, but is not available under that name anymore.} in
+conjunction with the @option{--create} operation to include a label
+entry in the archive as it is being created.
@table @option
@item --label=@var{archive-label}
the archive is being created, when used in conjunction with the
@option{--create} operation. Checks to make sure the archive label
matches the one specified (when used in conjunction with any other
-operation.
+operation).
@end table
If you create an archive using both
@smallexample
@group
$ @kbd{tar --verbose --list --file=iamanarchive}
-V--------- 0 0 0 1992-03-07 12:01 iamalabel--Volume Header--
--rw-r--r-- ringo user 40 1990-05-21 13:30 iamafilename
+V--------- 0/0 0 1992-03-07 12:01 iamalabel--Volume Header--
+-rw-r--r-- ringo/user 40 1990-05-21 13:30 iamafilename
@end group
@end smallexample
However, @option{--list} option will cause listing entire
contents of the archive, which may be undesirable (for example, if the
archive is stored on a tape). You can request checking only the volume
-by specifying @option{--test-label} option. This option reads only the
+label by specifying @option{--test-label} option. This option reads only the
first block of an archive, so it can be used with slow storage
devices. For example:
@end group
@end smallexample
- If @option{--test-label} is used with a single command line
-argument, @command{tar} compares the volume label with the
-argument. It exits with code 0 if the two strings match, and with code
-2 otherwise. In this case no output is displayed. For example:
+ If @option{--test-label} is used with one or more command line
+arguments, @command{tar} compares the volume label with each
+argument. It exits with code 0 if a match is found, and with code 1
+otherwise@footnote{Note that @GNUTAR{} versions up to 1.23 indicated
+mismatch with an exit code 2 and printed a spurious diagnostics on
+stderr.}. No output is displayed, unless you also used the
+@option{--verbose} option. For example:
@smallexample
@group
-$ @kbd{tar --test-label --file=iamanarchive 'iamalable'}
+$ @kbd{tar --test-label --file=iamanarchive 'iamalabel'}
@result{} 0
-$ @kbd{tar --test-label --file=iamanarchive 'iamalable' alabel}
+$ @kbd{tar --test-label --file=iamanarchive 'alabel'}
+@result{} 1
+@end group
+@end smallexample
+
+ When used with the @option{--verbose} option, @command{tar}
+prints the actual volume label (if any), and a verbose diagnostics in
+case of a mismatch:
+
+@smallexample
+@group
+$ @kbd{tar --test-label --verbose --file=iamanarchive 'iamalabel'}
+iamalabel
+@result{} 0
+$ @kbd{tar --test-label --verbose --file=iamanarchive 'alabel'}
+iamalabel
+tar: Archive label mismatch
@result{} 1
@end group
@end smallexample
@smallexample
@group
$ @kbd{tar -rf archive --label 'My volume' .}
-tar: Archive not labeled to match `My volume'
+tar: Archive not labeled to match 'My volume'
@end group
@end smallexample
creation time, it sounded logical to equally help the user taking care
of it when the archive is being read.
- The @option{--label} was once called @option{--volume}, but is not
-available under that name anymore.
-
You can also use @option{--label} to get a common information on
all tapes of a series. For having this information different in each
series created through a single script used on a regular basis, just
@smallexample
@group
-$ @kbd{tar cfMV /dev/tape "Daily backup for `date +%Y-%m-%d`"}
+$ @kbd{tar -cM -f /dev/tape -V "Daily backup for `date +%Y-%m-%d`"}
$ @kbd{tar --create --file=/dev/tape --multi-volume \
- --volume="Daily backup for `date +%Y-%m-%d`"}
+ --label="Daily backup for `date +%Y-%m-%d`"}
@end group
@end smallexample
- Also note that each label has its own date and time, which corresponds
-to when @GNUTAR{} initially attempted to write it,
+ Some more notes about volume labels:
+
+@itemize @bullet
+@item Each label has its own date and time, which corresponds
+to the time when @GNUTAR{} initially attempted to write it,
often soon after the operator launches @command{tar} or types the
-carriage return telling that the next tape is ready. Comparing date
-labels does give an idea of tape throughput only if the delays for
-rewinding tapes and the operator switching them were negligible, which
-is usually not the case.
+carriage return telling that the next tape is ready.
+
+@item Comparing date labels to get an idea of tape throughput is
+unreliable. It gives correct results only if the delays for rewinding
+tapes and the operator switching them were negligible, which is
+usually not the case.
+@end itemize
@node verify
@section Verifying Data as It is Stored
Once an archive is written, you should write protect the media to prevent
the archive from being accidentally overwritten or deleted. (This will
protect the archive from being changed with a tape or floppy drive---it
-will not protect it from magnet fields or other physical hazards).
+will not protect it from magnet fields or other physical hazards.)
The write protection device itself is usually an integral part of the
physical media, and can be a two position (write enabled/write
which can be removed from the center of a tape reel, or some other
changeable feature.
+@node Reliability and security
+@chapter Reliability and Security
+
+The @command{tar} command reads and writes files as any other
+application does, and is subject to the usual caveats about
+reliability and security. This section contains some commonsense
+advice on the topic.
+
+@menu
+* Reliability::
+* Security::
+@end menu
+
+@node Reliability
+@section Reliability
+
+Ideally, when @command{tar} is creating an archive, it reads from a
+file system that is not being modified, and encounters no errors or
+inconsistencies while reading and writing. If this is the case, the
+archive should faithfully reflect what was read. Similarly, when
+extracting from an archive, ideally @command{tar} ideally encounters
+no errors and the extracted files faithfully reflect what was in the
+archive.
+
+However, when reading or writing real-world file systems, several
+things can go wrong; these include permissions problems, corruption of
+data, and race conditions.
+
+@menu
+* Permissions problems::
+* Data corruption and repair::
+* Race conditions::
+@end menu
+
+@node Permissions problems
+@subsection Permissions Problems
+
+If @command{tar} encounters errors while reading or writing files, it
+normally reports an error and exits with nonzero status. The work it
+does may therefore be incomplete. For example, when creating an
+archive, if @command{tar} cannot read a file then it cannot copy the
+file into the archive.
+
+@node Data corruption and repair
+@subsection Data Corruption and Repair
+
+If an archive becomes corrupted by an I/O error, this may corrupt the
+data in an extracted file. Worse, it may corrupt the file's metadata,
+which may cause later parts of the archive to become misinterpreted.
+An tar-format archive contains a checksum that most likely will detect
+errors in the metadata, but it will not detect errors in the data.
+
+If data corruption is a concern, you can compute and check your own
+checksums of an archive by using other programs, such as
+@command{cksum}.
+
+When attempting to recover from a read error or data corruption in an
+archive, you may need to skip past the questionable data and read the
+rest of the archive. This requires some expertise in the archive
+format and in other software tools.
+
+@node Race conditions
+@subsection Race conditions
+
+If some other process is modifying the file system while @command{tar}
+is reading or writing files, the result may well be inconsistent due
+to race conditions. For example, if another process creates some
+files in a directory while @command{tar} is creating an archive
+containing the directory's files, @command{tar} may see some of the
+files but not others, or it may see a file that is in the process of
+being created. The resulting archive may not be a snapshot of the
+file system at any point in time. If an application such as a
+database system depends on an accurate snapshot, restoring from the
+@command{tar} archive of a live file system may therefore break that
+consistency and may break the application. The simplest way to avoid
+the consistency issues is to avoid making other changes to the file
+system while tar is reading it or writing it.
+
+When creating an archive, several options are available to avoid race
+conditions. Some hosts have a way of snapshotting a file system, or
+of temporarily suspending all changes to a file system, by (say)
+suspending the only virtual machine that can modify a file system; if
+you use these facilities and have @command{tar -c} read from a
+snapshot when creating an archive, you can avoid inconsistency
+problems. More drastically, before starting @command{tar} you could
+suspend or shut down all processes other than @command{tar} that have
+access to the file system, or you could unmount the file system and
+then mount it read-only.
+
+When extracting from an archive, one approach to avoid race conditions
+is to create a directory that no other process can write to, and
+extract into that.
+
+@node Security
+@section Security
+
+In some cases @command{tar} may be used in an adversarial situation,
+where an untrusted user is attempting to gain information about or
+modify otherwise-inaccessible files. Dealing with untrusted data
+(that is, data generated by an untrusted user) typically requires
+extra care, because even the smallest mistake in the use of
+@command{tar} is more likely to be exploited by an adversary than by a
+race condition.
+
+@menu
+* Privacy::
+* Integrity::
+* Live untrusted data::
+* Security rules of thumb::
+@end menu
+
+@node Privacy
+@subsection Privacy
+
+Standard privacy concerns apply when using @command{tar}. For
+example, suppose you are archiving your home directory into a file
+@file{/archive/myhome.tar}. Any secret information in your home
+directory, such as your SSH secret keys, are copied faithfully into
+the archive. Therefore, if your home directory contains any file that
+should not be read by some other user, the archive itself should be
+not be readable by that user. And even if the archive's data are
+inaccessible to untrusted users, its metadata (such as size or
+last-modified date) may reveal some information about your home
+directory; if the metadata are intended to be private, the archive's
+parent directory should also be inaccessible to untrusted users.
+
+One precaution is to create @file{/archive} so that it is not
+accessible to any user, unless that user also has permission to access
+all the files in your home directory.
+
+Similarly, when extracting from an archive, take care that the
+permissions of the extracted files are not more generous than what you
+want. Even if the archive itself is readable only to you, files
+extracted from it have their own permissions that may differ.
+
+@node Integrity
+@subsection Integrity
+
+When creating archives, take care that they are not writable by a
+untrusted user; otherwise, that user could modify the archive, and
+when you later extract from the archive you will get incorrect data.
+
+When @command{tar} extracts from an archive, by default it writes into
+files relative to the working directory. If the archive was generated
+by an untrusted user, that user therefore can write into any file
+under the working directory. If the working directory contains a
+symbolic link to another directory, the untrusted user can also write
+into any file under the referenced directory. When extracting from an
+untrusted archive, it is therefore good practice to create an empty
+directory and run @command{tar} in that directory.
+
+When extracting from two or more untrusted archives, each one should
+be extracted independently, into different empty directories.
+Otherwise, the first archive could create a symbolic link into an area
+outside the working directory, and the second one could follow the
+link and overwrite data that is not under the working directory. For
+example, when restoring from a series of incremental dumps, the
+archives should have been created by a trusted process, as otherwise
+the incremental restores might alter data outside the working
+directory.
+
+If you use the @option{--absolute-names} (@option{-P}) option when
+extracting, @command{tar} respects any file names in the archive, even
+file names that begin with @file{/} or contain @file{..}. As this
+lets the archive overwrite any file in your system that you can write,
+the @option{--absolute-names} (@option{-P}) option should be used only
+for trusted archives.
+
+Conversely, with the @option{--keep-old-files} (@option{-k}) and
+@option{--skip-old-files} options, @command{tar} refuses to replace
+existing files when extracting. The difference between the two
+options is that the former treats existing files as errors whereas the
+latter just silently ignores them.
+
+Finally, with the @option{--no-overwrite-dir} option, @command{tar}
+refuses to replace the permissions or ownership of already-existing
+directories. These options may help when extracting from untrusted
+archives.
+
+@node Live untrusted data
+@subsection Dealing with Live Untrusted Data
+
+Extra care is required when creating from or extracting into a file
+system that is accessible to untrusted users. For example, superusers
+who invoke @command{tar} must be wary about its actions being hijacked
+by an adversary who is reading or writing the file system at the same
+time that @command{tar} is operating.
+
+When creating an archive from a live file system, @command{tar} is
+vulnerable to denial-of-service attacks. For example, an adversarial
+user could create the illusion of an indefinitely-deep directory
+hierarchy @file{d/e/f/g/...} by creating directories one step ahead of
+@command{tar}, or the illusion of an indefinitely-long file by
+creating a sparse file but arranging for blocks to be allocated just
+before @command{tar} reads them. There is no easy way for
+@command{tar} to distinguish these scenarios from legitimate uses, so
+you may need to monitor @command{tar}, just as you'd need to monitor
+any other system service, to detect such attacks.
+
+While a superuser is extracting from an archive into a live file
+system, an untrusted user might replace a directory with a symbolic
+link, in hopes that @command{tar} will follow the symbolic link and
+extract data into files that the untrusted user does not have access
+to. Even if the archive was generated by the superuser, it may
+contain a file such as @file{d/etc/passwd} that the untrusted user
+earlier created in order to break in; if the untrusted user replaces
+the directory @file{d/etc} with a symbolic link to @file{/etc} while
+@command{tar} is running, @command{tar} will overwrite
+@file{/etc/passwd}. This attack can be prevented by extracting into a
+directory that is inaccessible to untrusted users.
+
+Similar attacks via symbolic links are also possible when creating an
+archive, if the untrusted user can modify an ancestor of a top-level
+argument of @command{tar}. For example, an untrusted user that can
+modify @file{/home/eve} can hijack a running instance of @samp{tar -cf
+- /home/eve/Documents/yesterday} by replacing
+@file{/home/eve/Documents} with a symbolic link to some other
+location. Attacks like these can be prevented by making sure that
+untrusted users cannot modify any files that are top-level arguments
+to @command{tar}, or any ancestor directories of these files.
+
+@node Security rules of thumb
+@subsection Security Rules of Thumb
+
+This section briefly summarizes rules of thumb for avoiding security
+pitfalls.
+
+@itemize @bullet
+
+@item
+Protect archives at least as much as you protect any of the files
+being archived.
+
+@item
+Extract from an untrusted archive only into an otherwise-empty
+directory. This directory and its parent should be accessible only to
+trusted users. For example:
+
+@example
+@group
+$ @kbd{chmod go-rwx .}
+$ @kbd{mkdir -m go-rwx dir}
+$ @kbd{cd dir}
+$ @kbd{tar -xvf /archives/got-it-off-the-net.tar.gz}
+@end group
+@end example
+
+As a corollary, do not do an incremental restore from an untrusted archive.
+
+@item
+Do not let untrusted users access files extracted from untrusted
+archives without checking first for problems such as setuid programs.
+
+@item
+Do not let untrusted users modify directories that are ancestors of
+top-level arguments of @command{tar}. For example, while you are
+executing @samp{tar -cf /archive/u-home.tar /u/home}, do not let an
+untrusted user modify @file{/}, @file{/archive}, or @file{/u}.
+
+@item
+Pay attention to the diagnostics and exit status of @command{tar}.
+
+@item
+When archiving live file systems, monitor running instances of
+@command{tar} to detect denial-of-service attacks.
+
+@item
+Avoid unusual options such as @option{--absolute-names} (@option{-P}),
+@option{--dereference} (@option{-h}), @option{--overwrite},
+@option{--recursive-unlink}, and @option{--remove-files} unless you
+understand their security implications.
+
+@end itemize
+
@node Changes
@appendix Changes
tar: Error exit delayed from previous errors
@end smallexample
-To treat member names as globbing patterns, use --wildcards option.
+To treat member names as globbing patterns, use the @option{--wildcards} option.
If you want to tar to mimic the behavior of versions prior to 1.15.91,
add this option to your @env{TAR_OPTIONS} variable.
distribution tarballs. @xref{Formats,v7}, for the detailed discussion
of this issue and its implications.
-@FIXME{Change the first argument to tar-formats when the new Automake is
-out. The proposition to add @anchor{} to the appropriate place of its
-docs was accepted by Automake people --Sergey 2006-05-25}.
-@xref{Options, tar-v7, Changing Automake's Behavior,
+@xref{Options, tar-formats, Changing Automake's Behavior,
automake, GNU Automake}, for a description on how to use various
archive formats with @command{automake}.
Earlier versions of @GNUTAR{} understood @option{-l} option as a
synonym for @option{--one-file-system}. Since such usage contradicted
to UNIX98 specification and harmed compatibility with other
-implementation, it was declared deprecated in version 1.14. However,
+implementations, it was declared deprecated in version 1.14. However,
to facilitate transition to its new semantics, it was supported by
versions 1.15 and 1.15.90. The present use of @option{-l} as a short
variant of @option{--check-links} was introduced in version 1.15.91.
@appendix Free Software Needs Free Documentation
@include freemanuals.texi
-@node Copying This Manual
-@appendix Copying This Manual
-
-@menu
-* GNU Free Documentation License:: License for copying this manual
-@end menu
+@node GNU Free Documentation License
+@appendix GNU Free Documentation License
@include fdl.texi
This appendix contains an index of all @GNUTAR{} long command line
options. The options are listed without the preceding double-dash.
-For a cross-reference of short command line options, @ref{Short Option Summary}.
+For a cross-reference of short command line options, see
+@ref{Short Option Summary}.
@printindex op
projects / chaz / tar / blobdiff