@set xref-owner @xref{Option Summary}
@set pxref-owner @pxref{Option Summary}
-@set op-format @kbd{--format}
+@set op-format @kbd{--format} (@kbd{-H})
@set ref-format @ref{format}
@set xref-format @xref{format}
@set pxref-format @pxref{format}
@set xref-remove-files @xref{Writing}
@set pxref-remove-files @pxref{Writing}
+@set op-rmt-command @kbd{rmt-command=@var{command}}
@set op-rsh-command @kbd{rsh-command=@var{command}}
@set op-same-order @kbd{--same-order} (@kbd{--preserve-order}, @kbd{-s})
@set xref-starting-file @xref{Scarce}
@set pxref-starting-file @pxref{Scarce}
-@set op-strip-path @kbd{--strip-path}
-@set ref-strip-path @ref{--strip-path}
-@set xref-strip-path @xref{--strip-path}
-@set pxref-strip-path @pxref{--strip-path}
+@set op-strip-components @kbd{--strip-components}
+@set ref-strip-components @ref{--strip-components}
+@set xref-strip-components @xref{--strip-components}
+@set pxref-strip-components @pxref{--strip-components}
@set op-suffix @kbd{--suffix=@var{suffix}}
@set ref-suffix @ref{Backup options}
@end smallexample
It is also a good practice to examine contents of the archive
-before extracting it, using @option{op-list} option, possibly combined
-with @option{op-verbose}.
+before extracting it, using @value{op-list} option, possibly combined
+with @value{op-verbose}.
@node failing commands
@subsection Commands That Will Fail
Directs @command{tar} to remove the source file from the file system after
appending it to an archive. @FIXME-xref{}
+@item --rmt-command=@var{cmd}
+
+Notifies @command{tar} that it should use @var{cmd} instead of
+the default @file{/usr/libexec/rmt} (@pxref{Remote Tape Server}).
+
@item --rsh-command=@var{cmd}
Notifies @command{tar} that is should use @var{cmd} to communicate with remote
files in the archive until it finds one that matches @var{name}.
@xref{Scarce}.
-@item --strip-path=@var{number}
+@item --strip-components=@var{number}
Strip given @var{number} of leading components from file names before
-extraction. For example, if archive @file{archive.tar} contained
+extraction.@footnote{This option was called @option{--strip-path} in
+version 1.14.} For example, if archive @file{archive.tar} contained
@file{/some/file/name}, then running
@smallexample
-tar --extract --file archive.tar --strip-path=2
+tar --extract --file archive.tar --strip-components=2
@end smallexample
@noindent
versions of archive members to an existing archive. To learn how to
do this with @samp{--update}, @pxref{update}.)
-@FIXME{Explain in second paragraph whether you can get to the previous
-version -- explain whole situation somewhat more clearly.}
-
If you use @value{op-append} to add a file that has the same name as an
archive member to an archive containing that archive member, then the
old member is not deleted. What does happen, however, is somewhat
-complex. @command{tar} @emph{allows} you to have infinite numbers of files
+complex. @command{tar} @emph{allows} you to have infinite number of files
with the same name. Some operations treat these same-named members no
differently than any other set of archive members: for example, if you
view an archive with @value{op-list}, you will see all of those members
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. Thus, only the most recently archived
+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.
+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
+this option, it will extract only the first copy of the file. You
+may also give this option an argument specifying the number of
+copy to be extracted. Thus, for example if the archive
+@file{archive.tar} contained three copies of file @file{myfile}, then
+the command
+
+@smallexample
+tar --extract --file archive.tar --occurrence=2 myfile
+@end smallexample
+
+@noindent
+would extract only the second copy. @xref{Option Summary,---occurrence}, for the description of @value{op-occurrence} option.
+
@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...}
+MMwtSN node; not sure. i didn't know how to make it simpler...
-There are a few ways to get around this. @FIXME-xref{Multiple Members
+There are a few ways to get around this. (maybe xref Multiple Members
with the Same Name.}
@cindex Members, replacing with other members
(note the different creation dates and file sizes). If you extract
the archive, the older version of the file @file{blues} will be
replaced by the newer version. You can confirm this by extracting
-the archive and running @samp{ls} on the directory. @xref{Writing},
-for more information. (@emph{Please note:} This is the case unless
-you employ the @value{op-backup} option. @FIXME-ref{Multiple Members
-with the Same Name}.)
+the archive and running @samp{ls} on the directory.
+
+If you wish to extract the first occurrence of the file @file{blues}
+from the archive, use @value{op-occurrence} option, as shown in
+the following example:
+
+@smallexample
+$ @kbd{tar --extract -vv --occurrence --file=collection.tar blues}
+-rw-rw-rw- me user 21 1996-09-23 16:44 blues
+@end smallexample
+
+@xref{Writing}, for more information on @value{op-extract} and
+@xref{Option Summary, --occurrence}, for the description of
+@value{op-occurrence} option.
@node update
@subsection Updating an Archive
not be welcome at all that @GNUTAR{} removes the
whole hierarchy just to make room for the link to be reinstated
(unless it @emph{also} simultaneously restores the full
-@file{/usr/local2}, of course! @GNUTAR{} is indeed
+@file{/usr/local2}, of course!) @GNUTAR{} is indeed
able to remove a whole hierarchy to reestablish a symbolic link, for
example, but @emph{only if} @value{op-recursive-unlink} is specified
to allow this behavior. In any case, single files are silently
@end ifclear
-This chapter documents both the provided FSF scripts and @command{tar}
+This chapter documents both the provided shell scripts and @command{tar}
options which are more specific to usage as a backup tool.
To @dfn{back up} a file system means to create archives that contain
be excluded from the backup. Exclude file lists are searched in
/etc/tar-backup directory. A common use for exclude file lists
is to exclude files containing security-sensitive information
-(e.g. @file{/etc/shadow} from backups.
+(e.g. @file{/etc/shadow} from backups).
This variable affects only @code{backup}.
@end defvr
@end defvr
@defvr {Backup variable} MT_REWIND
-THe name of @dfn{rewind} function. The default definition is as
+The name of @dfn{rewind} function. The default definition is as
follows:
@smallexample
@subsection User Hooks
@dfn{User hooks} are shell functions executed before and after
-each @command{tar} invocations. Thus, there are @dfn{backup
+each @command{tar} invocation. Thus, there are @dfn{backup
hooks}, which are executed before and after dumping each file
system, and @dfn{restore hooks}, executed before and
after restoring a file system. Each user hook is a shell function
taking four arguments:
@deffn {User Hook Function} hook @var{level} @var{host} @var{fs} @var{fsname}
-The arguments are:
+Its arguments are:
@table @var
@item level
@node backup-specs example
@subsection An Example Text of @file{Backup-specs}
-The following is the text of @file{backup-specs} as it appears at FSF:
+The following is an example of @file{backup-specs}:
@smallexample
# site-specific parameters for file system backup.
messages that were generated, as well as how much space was left in
the media volume after the last volume of the archive was written.
You should check this log file after every backup. The file name is
-@file{log-@var{mmm-ddd-yyyy}-level-@var{n}}, where @var{n} represents
-current dump level number.
+@file{log-@var{mm-dd-yyyy}-level-@var{n}}, where @var{mm-dd-yyyy}
+represents current date, and @var{n} represents current dump level number.
The script also prints the name of each system being dumped to the
standard output.
@itemx --force
Force backup even if today's log file already exists.
-@item -v@var{level}
+@item -v[@var{level}]
@itemx --verbose[=@var{level}]
Set verbosity level. The higher the level is, the more debugging
information will be output during execution. Devault @var{level}
@itemx --level=@var{level}
Start restoring from the given backup level, instead of the default 0.
-@item -v@var{level}
+@item -v[@var{level}]
@itemx --verbose[=@var{level}]
Set verbosity level. The higher the level is, the more debugging
information will be output during execution. Devault @var{level}
(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{/usr/ucb/rmt} program installed. If you need to use a
-file whose name includes a colon, then the remote tape drive behavior
+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
+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 @value{op-force-local} option.
@FIXME{i know we went over this yesterday, but bob (and now i do again,
uses. You could be sued for patent infringement merely by running
@command{compress}.
-I have one question, or maybe it's a suggestion if there isn't a way
+@FIXME{I have one question, or maybe it's a suggestion if there isn't a way
to do it now. I would like to use @value{op-gzip}, but I'd also like
the output to be fed through a program like @acronym{GNU}
@command{ecc} (actually, right now that's @samp{exactly} what I'd like
It has been reported that if one writes compressed data (through the
@value{op-gzip} or @value{op-compress} options) to a DLT and tries to use
the DLT compression mode, the data will actually get bigger and one will
-end up with less space on the tape.
+end up with less space on the tape.}
@node sparse
@subsection Archiving Sparse Files
@samp{hostname:file name}. If the @var{hostname} contains an @dfn{at}
sign (@kbd{@@}), it is treated as @samp{user@@hostname:file name}. In
either case, @command{tar} will invoke the command @command{rsh} (or
-@command{remsh}) to start up an @file{/etc/rmt} on the remote machine. If
-you give an alternate login name, it will be given to the @command{rsh}.
-Naturally, the remote machine must have an executable @file{/etc/rmt}.
-This program is free software from the University of California, and a
-copy of the source code can be found with the sources for @command{tar};
-it's compiled and installed by default.
+@command{remsh}) to start up an @command{/usr/libexec/rmt} on the remote
+machine. If you give an alternate login name, it will be given to the
+@command{rsh}.
+Naturally, the remote machine must have an executable
+@command{/usr/libexec/rmt}. This program is free software from the
+University of California, and a copy of the source code can be found
+with the sources for @command{tar}; it's compiled and installed by default.
+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 @value{op-rmt-command} option (@xref{Option Summary,
+---rmt-command}, for detailed description of this option. @xref{Remote
+Tape Server}, for the description of @command{rmt} command).
If this option is not given, but the environment variable @env{TAPE}
is set, its value is used; otherwise, old versions of @command{tar}
@pindex rmt
In order to access the tape drive on a remote machine, @command{tar}
uses the remote tape server written at the University of California at
-Berkeley. The remote tape server must be installed as @file{/etc/rmt}
-on any machine whose tape drive you want to use. @command{tar} calls
-@file{/etc/rmt} by running an @command{rsh} or @command{remsh} to the remote
-machine, optionally using a different login name if one is supplied.
+Berkeley. The remote tape server must be installed as
+@file{@var{prefix}/libexec/rmt} on any machine whose tape drive you
+want to use. @command{tar} calls @command{rmt} by running an
+@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. Instructions for compiling
-and installing it are included in the @file{Makefile}.
+California, but can be freely distributed. It is compiled and
+installed by default.
@cindex absolute file names
Unless you use the @value{op-absolute-names} option, @GNUTAR{}
projects / chaz / tar / blobdiff