from archives.
Copyright @copyright{} 1992, 1994, 1995, 1996, 1997, 1999, 2000, 2001,
-2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
+2003, 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc.
@quotation
Permission is granted to copy, distribute and/or modify this document
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.''
+(a) The FSF's Back-Cover Text is: ``You have the freedom to
+copy and modify this GNU manual. Buying copies from the FSF
+supports it in developing GNU and promoting software freedom.''
@end quotation
@end copying
* help::
* defaults::
* verbose::
+* checkpoints::
* interactive::
The Three Option Styles
* 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.
@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.}
* help::
* defaults::
* verbose::
+* checkpoints::
* interactive::
@end menu
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{--checklist-action} below. For a detailed description, see
+@ref{checkpoints}.
+
+@opsummary{checkpoint-action}
+@item --checkpoint-action=@var{action}
+Instruct @command{tar} to execute an action upon hitting a
+breakpoint. Here we give only a brief outline. @xref{checkpoints},
+for a complete description.
+
+The @var{action} argument can be one of the following:
+
+@table @asis
+@item bell
+Produce an audible bell on the console.
+
+@item dot
+@itemx .
+Print a single dot on the standard listing stream.
+
+@item echo
+Display a textual message on the standard error, with the status and
+number of the checkpoint. This is the default.
+
+@item echo=@var{string}
+Display @var{string} on the standard error. Before output, the string
+is subject to meta-character expansion.
+
+@item exec=@var{command}
+Execute the given @var{command}.
+
+@item sleep=@var{time}
+Wait for @var{time} seconds.
+
+@item ttyout=@var{string}
+Output @var{string} on the current console (@file{/dev/tty}).
+@end table
+
+Several @option{--checkpoint-action} options can be specified. The
+supplied actions will be executed in order of their appearance in the
+command line.
+
+Using @option{--checkpoint-action} without @option{--checkpoint}
+assumes default checkpoint frequency of one checkpoint per 10 records.
@opsummary{check-links}
@item --check-links
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 --exclude-tag-all=@var{file}
Exclude from dump any directory containing file named @var{file}.
-@xref{exclude}.
+@xref{exclude}.
@opsummary{exclude-vcs}
@item --exclude-vcs
@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 --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{overwrite}
@item --overwrite
@smallexample
tar (GNU tar) @value{VERSION}
-Copyright (C) 2006 Free Software Foundation, Inc.
+Copyright (C) 2008 Free Software Foundation, Inc.
This is free software. You may redistribute copies of it under the terms
of the GNU General Public License <http://www.gnu.org/licenses/gpl.html>.
There is NO WARRANTY, to the extent permitted by law.
@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
favor of the tape where the file appears earliest (closest to the
front of the tape). @xref{backup}.
+@node checkpoints
+@section Checkpoints
+@cindex checkpoints, defined
+@opindex checkpoint
+@opindex checkpoint-action
+
+A @dfn{checkpoint} is a moment of time before writing @var{n}th record to
+the archive (a @dfn{write checkpoint}), or before reading @var{n}th record
+from the archive (a @dfn{read checkpoint}). Checkpoints allow to
+periodically execute arbitrary actions.
+
+The checkpoint facility is enabled using the following option:
+
+@table @option
+@xopindex{checkpoint, defined}
+@item --checkpoint[=@var{n}]
+Schedule checkpoints before writing or reading each @var{n}th record.
+The default value for @var{n} is 10.
+@end table
+
+A list of arbitrary @dfn{actions} can be executed at each checkpoint.
+These actions include: pausing, displaying textual messages, and
+executing arbitrary external programs. Actions are defined using
+the @option{--checkpoint-action} option.
+
+@table @option
+@xopindex{checkpoint-action, defined}
+@item --checkpoint-action=@var{action}
+Execute an @var{action} at each checkpoint.
+@end table
+
+@cindex @code{echo}, checkpoint action
+The simplest value of @var{action} is @samp{echo}. It instructs
+@command{tar} to display the default message on the standard error
+stream upon arriving at each checkpoint. The default message is (in
+@acronym{POSIX} locale) @samp{Write checkpoint @var{n}}, for write
+checkpoints, and @samp{Read checkpoint @var{n}}, for read checkpoints.
+Here, @var{n} represents ordinal number of the checkpoint.
+
+In another locales, translated versions of this message are used.
+
+This is the default action, so running:
+
+@smallexample
+$ @kbd{tar -c --checkpoint=1000 --checkpoint-action=echo} /var
+@end smallexample
+
+@noindent
+is equivalent to:
+
+@smallexample
+$ @kbd{tar -c --checkpoint=1000} /var
+@end smallexample
+
+The @samp{echo} action also allows to supply a customized message.
+You do so by placing an equals sign and the message right after it,
+e.g.:
+
+@smallexample
+--checkpoint-action="echo=Hit %s checkpoint #%u"
+@end smallexample
+
+The @samp{%s} and @samp{%u} in the above example are
+@dfn{meta-characters}. The @samp{%s} meta-character is replaced with
+the @dfn{type} of the checkpoint: @samp{write} or
+@samp{read} (or a corresponding translated version in locales other
+than @acronym{POSIX}). The @samp{%u} meta-character is replaced with
+the ordinal number of the checkpoint. Thus, the above example could
+produce the following output when used with the @option{--create}
+option:
+
+@smallexample
+tar: Hit write checkpoint #10
+tar: Hit write checkpoint #20
+tar: Hit write checkpoint #30
+@end smallexample
+
+Aside from meta-character expansion, the message string is subject to
+@dfn{unquoting}, during which the backslash @dfn{escape sequences} are
+replaced with their corresponding @acronym{ASCII} characters
+(@pxref{escape sequences}). E.g. the following action will produce an
+audible bell and the message described above at each checkpoint:
+
+@smallexample
+--checkpoint-action='echo=\aHit %s checkpoint #%u'
+@end smallexample
+
+@cindex @code{bell}, checkpoint action
+There is also a special action which produces an audible signal:
+@samp{bell}. It is not equivalent to @samp{echo='\a'}, because
+@samp{bell} sends the bell directly to the console (@file{/dev/tty}),
+whereas @samp{echo='\a'} sends it to the standard error.
+
+@cindex @code{ttyout}, checkpoint action
+The @samp{ttyout=@var{string}} action outputs @var{string} to
+@file{/dev/tty}, so it can be used even if the standard output is
+redirected elsewhere. The @var{string} is subject to the same
+modifications as with @samp{echo} action. In contrast to the latter,
+@samp{ttyout} does not prepend @command{tar} executable name to the
+string, nor does it output a newline after it. For example, the
+following action will print the checkpoint message at the same screen
+line, overwriting any previous message:
+
+@smallexample
+--checkpoint-action="ttyout=\rHit %s checkpoint #%u"
+@end smallexample
+
+@cindex @code{dot}, checkpoint action
+Another available checkpoint action is @samp{dot} (or @samp{.}). It
+instructs @command{tar} to print a single dot on the standard listing
+stream, e.g.:
+
+@smallexample
+$ @kbd{tar -c --checkpoint=1000 --checkpoint-action=dot} /var
+...
+@end smallexample
+
+For compatibility with previous @GNUTAR{} versions, this action can
+be abbreviated by placing a dot in front of the checkpoint frequency,
+as shown in the previous section.
+
+@cindex @code{sleep}, checkpoint action
+Yet another action, @samp{sleep}, pauses @command{tar} for a specified
+amount of seconds. The following example will stop for 30 seconds at each
+checkpoint:
+
+@smallexample
+$ @kbd{tar -c --checkpoint=1000 --checkpoint-action=sleep=30}
+@end smallexample
+
+@cindex @code{exec}, checkpoint action
+Finally, the @code{exec} action executes a given external program.
+For example:
+
+@smallexample
+$ @kbd{tar -c --checkpoint=1000 --checkpoint-action=exec=/sbin/cpoint}
+@end smallexample
+
+This program is executed using @command{/bin/sh -c}, with no
+additional arguments. Its exit code is ignored. It gets a copy of
+@command{tar}'s environment plus the following variables:
+
+@table @env
+@vrindex TAR_VERSION, checkpoint script environment
+@item TAR_VERSION
+@GNUTAR{} version number.
+
+@vrindex TAR_ARCHIVE, checkpoint script environment
+@item TAR_ARCHIVE
+The name of the archive @command{tar} is processing.
+
+@vrindex TAR_BLOCKING_FACTOR, checkpoint script environment
+@item TAR_BLOCKING_FACTOR
+Current blocking factor (@pxref{Blocking}.
+
+@vrindex TAR_CHECKPOINT, checkpoint script environment
+@item TAR_CHECKPOINT
+The checkpoint number.
+
+@vrindex TAR_SUBCOMMAND, checkpoint script environment
+@item TAR_SUBCOMMAND
+A short option describing the operation @command{tar} is executing
+@xref{Operations}, for a complete list of subcommand options.
+
+@vrindex TAR_FORMAT, checkpoint script environment
+@item TAR_FORMAT
+Format of the archive being processed. @xref{Formats}, for a complete
+list of archive format names.
+@end table
+
+Any number of actions can be defined, by supplying several
+@option{--checkpoint-action} options in the command line. For
+example, the command below displays two messages, pauses
+execution for 30 seconds and executes the @file{/sbin/cpoint} script:
+
+@example
+@group
+$ @kbd{tar -c -f arc.tar \
+ --checkpoint-action='\aecho=Hit %s checkpoint #%u' \
+ --checkpoint-action='echo=Sleeping for 30 seconds' \
+ --checkpoint-action='sleep=30' \
+ --checkpoint-action='exec=/sbin/cpoint'}
+@end group
+@end example
+
+This example also illustrates the fact that
+@option{--checkpoint-action} can be used without
+@option{--checkpoint}. In this case, the default checkpoint frequency
+(at each 10th record) is assumed.
+
@node interactive
@section Asking for Confirmation During Operations
@cindex Interactive operation
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:
@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
@var{regexp} and @var{replace} are described in detail in
@ref{The "s" Command, The "s" Command, The `s' Command, sed, GNU sed}.
+As in @command{sed}, you can give several replace expressions,
+separated by a semicolon.
+
Supported @var{flags} are:
@table @samp
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
@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.
+using it, because it is by far less effective than other compression
+programs@footnote{It also had patent problems in the past.}.
Creating a compressed archive is simple: you just specify a
@dfn{compression option} along with the usual archive creation
commands. The compression option is @option{-z} (@option{--gzip}) to
create a @command{gzip} compressed archive, @option{-j}
(@option{--bzip2}) to create a @command{bzip2} compressed archive,
-@command{lzma} to create an @asis{LZMA} compressed archive and
+@option{--lzma} to create an @asis{LZMA} compressed archive and
@option{-Z} (@option{--compress}) to use @command{compress} program.
For example:
@end smallexample
For a complete list of file name suffixes recognized by @GNUTAR{},
-@ref{auto-compress}.
+@ref{auto-compress}.
Reading compressed archive is even simpler: you don't need to specify
any additional options as @GNUTAR{} recognizes its format
@itemx --uncompress
Filter the archive through @command{compress}. Otherwise like @option{--gzip}.
-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}.
-
@opindex use-compress-program
@item --use-compress-program=@var{prog}
Use external compression program @var{prog}. Use this option if you
@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.
symbolic links, and moreover, your distribution might be unusable if
it contains unresolved symbolic links.
+@node hard links
+@subsection Hard Links
+@UNREVISED{}
+@cindex File names, using hard links
+@cindex hard links, dereferencing
+@cindex dereferencing hard links
+
+Normally, when @command{tar} archives a hard link, it writes a
+block to the archive naming the target of the link (a @samp{1} type
+block). In that way, the actual file contents is stored in file only
+once. For example, consider the following two files:
+
+@smallexample
+@group
+$ ls
+-rw-r--r-- 2 gray staff 4 2007-10-30 15:11 one
+-rw-r--r-- 2 gray staff 4 2007-10-30 15:11 jeden
+@end group
+@end smallexample
+
+Here, @file{jeden} is a link to @file{one}. When archiving this
+directory with a verbose level 2, you will get an output similar to
+the following:
+
+@smallexample
+$ tar cfvv ../archive.tar .
+drwxr-xr-x gray/staff 0 2007-10-30 15:13 ./
+-rw-r--r-- gray/staff 4 2007-10-30 15:11 ./jeden
+hrw-r--r-- gray/staff 0 2007-10-30 15:11 ./one link to ./jeden
+@end smallexample
+
+The last line shows that, instead of storing two copies of the file,
+@command{tar} stored it only once, under the name @file{jeden}, and
+stored file @file{one} as a hard link to this file.
+
+It may be important to know that all hard links to the given file are
+stored in the archive. For example, this may be necessary for exact
+reproduction of the file system. The following option does that:
+
+@table @option
+@xopindex{check-links, described}
+@item --check-links
+@itemx -l
+Check the number of links dumped for each processed file. If this
+number does not match the total number of hard links for the file, print
+a warning message.
+@end table
+
+For example, trying to archive only file @file{jeden} with this option
+produces the following diagnostics:
+
+@smallexample
+$ tar -c -f ../archive.tar jeden
+tar: Missing links to `jeden'.
+@end smallexample
+
+Although creating special records for hard links helps keep a faithful
+record of the file system contents and makes archives more compact, it
+may present some difficulties when extracting individual members from
+the archive. For example, trying to extract file @file{one} from the
+archive created in previous examples produces, in the absense of file
+@file{jeden}:
+
+@smallexample
+$ tar xf archive.tar ./one
+tar: ./one: Cannot hard link to `./jeden': No such file or directory
+tar: Error exit delayed from previous errors
+@end smallexample
+
+The reason for this behavior is that @command{tar} cannot seek back in
+the archive to the previous member (in this case, @file{one}), to
+extract it@footnote{There are plans to fix this in future releases.}.
+If you wish to avoid such problems at the cost of a bigger archive,
+use the following option:
+
+@table @option
+@xopindex{hard-dereference, described}
+@item --hard-dereference
+Dereference hard links and store the files they refer to.
+@end table
+
+For example, trying this option on our two sample files, we get two
+copies in the archive, each of which can then be extracted
+independently of the other:
+
+@smallexample
+@group
+$ tar -c -vv -f ../archive.tar --hard-dereference .
+drwxr-xr-x gray/staff 0 2007-10-30 15:13 ./
+-rw-r--r-- gray/staff 4 2007-10-30 15:11 ./jeden
+-rw-r--r-- gray/staff 4 2007-10-30 15:11 ./one
+@end group
+@end smallexample
+
@node old
@subsection Old V7 Archives
@cindex Format, old style
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
@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