* NEWS: Update.
* THANKS: Update.
* doc/snapshot.texi, doc/snapshot.texi,
doc/sparse.texi, doc/tar-snapshot-edit.texi,
doc/tar.texi: Spellchecked and proof-read. Thanks
to Denis Excoffier.
* gnulib.modules: Remove utime.
-GNU tar NEWS - User visible changes. 2010-02-25
+GNU tar NEWS - User visible changes. 2010-03-10
Please send GNU tar bug reports to <bug-tar@gnu.org>
\f
Please send GNU tar bug reports to <bug-tar@gnu.org>
\f
** Fix storing and listing of the volume labels in POSIX format.
** Improve algorithm for splitting long file names (ustar
format).
** Fix storing and listing of the volume labels in POSIX format.
** Improve algorithm for splitting long file names (ustar
format).
+** Fix possible memory overflow in the rmt client code (CVE-2010-0624).
\f
version 1.22 - Sergey Poznyakoff, 2009-03-05
\f
version 1.22 - Sergey Poznyakoff, 2009-03-05
David Taylor taylor@think.com
Dean Gaudet dgaudet@watdragon.uwaterloo.ca
Demizu Noritoshi nori-d@is.aist-nara.ac.jp
David Taylor taylor@think.com
Dean Gaudet dgaudet@watdragon.uwaterloo.ca
Demizu Noritoshi nori-d@is.aist-nara.ac.jp
+Denis Excoffier denis.excoffier@airbus.com
Denis Fortin fortin@acm.org
Dennis Pixton dennis@math.binghamton.edu
Dick Streefland dicks@tasking.nl
Denis Fortin fortin@acm.org
Dennis Pixton dennis@math.binghamton.edu
Dick Streefland dicks@tasking.nl
This appendix describes all three formats in detail.
@enumerate 0
This appendix describes all three formats in detail.
@enumerate 0
-@cindex format 0, snapshot file
+@cindex format 0, snapshot file
@cindex snapshot file, format 0
@cindex snapshot file, format 0
@samp{Format 0} snapshot file begins with a line containing a
decimal number that represents a @acronym{UNIX} timestamp of the
beginning of the last archivation. This line is followed by directory
metadata descriptions, one per line. Each description has the
@samp{Format 0} snapshot file begins with a line containing a
decimal number that represents a @acronym{UNIX} timestamp of the
beginning of the last archivation. This line is followed by directory
metadata descriptions, one per line. Each description has the
@smallexample
@var{nfs}@var{dev} @var{inode} @var{name}
@smallexample
@var{nfs}@var{dev} @var{inode} @var{name}
backslashes, etc.) are quoted.
@end table
backslashes, etc.) are quoted.
@end table
-@cindex format 1, snapshot file
+@cindex format 1, snapshot file
@cindex snapshot file, format 1
@cindex snapshot file, format 1
@samp{Format 1} snapshot file begins with a line specifying the
format of the file. This line has the following structure:
@samp{Format 1} snapshot file begins with a line specifying the
format of the file. This line has the following structure:
where @var{tar-version} is the version number of @GNUTAR{}
implementation that created this snapshot, and
@var{incr-format-version} is the version number of the snapshot format
where @var{tar-version} is the version number of @GNUTAR{}
implementation that created this snapshot, and
@var{incr-format-version} is the version number of the snapshot format
-(in this case @samp{1}).
+(in this case @samp{1}).
Next line contains two decimal numbers, representing the
time of the last backup. First number is the number of seconds, the
Next line contains two decimal numbers, representing the
time of the last backup. First number is the number of seconds, the
@var{nfs}, @var{dev}, @var{inode} and @var{name} have the same meaning
as with @samp{format 0}.
@var{nfs}, @var{dev}, @var{inode} and @var{name} have the same meaning
as with @samp{format 0}.
-@cindex format 2, snapshot file
+@cindex format 2, snapshot file
@cindex snapshot file, format 2
@cindex snapshot file, format 2
- A snapshot file begins with a format identifier, as described for
+@item
+ @samp{Format 2} snapshot file begins with a format identifier, as described for
version 1, e.g.:
@smallexample
version 1, e.g.:
@smallexample
time of the last backup. First number is the number of seconds, the
second one is the number of nanoseconds, since the beginning of the
epoch. These are followed by arbitrary number of directory records.
time of the last backup. First number is the number of seconds, the
second one is the number of nanoseconds, since the beginning of the
epoch. These are followed by arbitrary number of directory records.
Each @dfn{directory record} contains a set of metadata describing a
particular directory. Parts of a directory record are delimited with
@acronym{ASCII} 0 characters. The following table describes each
Each @dfn{directory record} contains a set of metadata describing a
particular directory. Parts of a directory record are delimited with
@acronym{ASCII} 0 characters. The following table describes each
@item mtime-nano @tab Number @tab Modification time, nanoseconds;
@item dev-no @tab Number @tab Device number;
@item i-no @tab Number @tab I-node number;
@item mtime-nano @tab Number @tab Modification time, nanoseconds;
@item dev-no @tab Number @tab Device number;
@item i-no @tab Number @tab I-node number;
-@item name @tab String @tab Directory name; In contrast to the
-previous versions it is not quoted.
+@item name @tab String @tab Directory name; in contrast to the
+previous versions it is not quoted;
@item contents @tab Dumpdir @tab Contents of the directory;
@xref{Dumpdir}, for a description of its format.
@item contents @tab Dumpdir @tab Contents of the directory;
@xref{Dumpdir}, for a description of its format.
@end multitable
Dumpdirs stored in snapshot files contain only records of types
@end multitable
Dumpdirs stored in snapshot files contain only records of types
earliest version featuring this support that I was able to find was 1.09,
released in November, 1990. The format introduced back then is called
@dfn{old GNU} sparse format and in spite of the fact that its design
earliest version featuring this support that I was able to find was 1.09,
released in November, 1990. The format introduced back then is called
@dfn{old GNU} sparse format and in spite of the fact that its design
-contained many flaws, it was the only format @GNUTAR{} supported
+contained many flaws, it was the only format @GNUTAR{} supported
until version 1.14 (May, 2004), which introduced initial support for
sparse archives in @acronym{PAX} archives (@pxref{posix}). This
until version 1.14 (May, 2004), which introduced initial support for
sparse archives in @acronym{PAX} archives (@pxref{posix}). This
-format was not free from design flows, either and it was subsequently
+format was not free from design flaws, either and it was subsequently
improved in versions 1.15.2 (November, 2005) and 1.15.92 (June,
improved in versions 1.15.2 (November, 2005) and 1.15.92 (June,
In addition to GNU sparse format, @GNUTAR{} is able to read and
extract sparse files archived by @command{star}.
In addition to GNU sparse format, @GNUTAR{} is able to read and
extract sparse files archived by @command{star}.
@cindex sparse formats, Old GNU
@cindex Old GNU sparse format
@cindex sparse formats, Old GNU
@cindex Old GNU sparse format
-The format introduced some time around 1990 (v. 1.09). It was
+The format introduced in November 1990 (v. 1.09) was
designed on top of standard @code{ustar} headers in such an
unfortunate way that some of its fields overwrote fields required by
POSIX.
designed on top of standard @code{ustar} headers in such an
unfortunate way that some of its fields overwrote fields required by
POSIX.
@end multitable
Each of @code{sparse_header} object at offset 386 describes a single
@end multitable
Each of @code{sparse_header} object at offset 386 describes a single
-data chunk. It has the following structure:
+data chunk. It has the following structure:
@multitable @columnfractions 0.10 0.10 0.20 0.60
@headitem Offset @tab Size @tab Data type @tab Contents
@multitable @columnfractions 0.10 0.10 0.20 0.60
@headitem Offset @tab Size @tab Data type @tab Contents
@multitable @columnfractions 0.10 0.10 0.20 0.20 0.40
@headitem Offset @tab Size @tab Name @tab Data type @tab Contents
@item 0 @tab 21 @tab sp @tab @code{sparse_header} @tab
@multitable @columnfractions 0.10 0.10 0.20 0.20 0.40
@headitem Offset @tab Size @tab Name @tab Data type @tab Contents
@item 0 @tab 21 @tab sp @tab @code{sparse_header} @tab
@item 504 @tab 1 @tab isextended @tab Bool @tab @code{1} if an
extension sparse header follows, or @code{0} otherwise.
@end multitable
@item 504 @tab 1 @tab isextended @tab Bool @tab @code{1} if an
extension sparse header follows, or @code{0} otherwise.
@end multitable
@table @code
@vrindex GNU.sparse.size, extended header variable
@item GNU.sparse.size
@table @code
@vrindex GNU.sparse.size, extended header variable
@item GNU.sparse.size
-Real size of the stored file
+Real size of the stored file;
@item GNU.sparse.numblocks
@vrindex GNU.sparse.numblocks, extended header variable
@item GNU.sparse.numblocks
@vrindex GNU.sparse.numblocks, extended header variable
-Number of blocks in the sparse map
+Number of blocks in the sparse map;
@item GNU.sparse.offset
@vrindex GNU.sparse.offset, extended header variable
@item GNU.sparse.offset
@vrindex GNU.sparse.offset, extended header variable
-Offset of the data block
+Offset of the data block;
@item GNU.sparse.numbytes
@vrindex GNU.sparse.numbytes, extended header variable
@item GNU.sparse.numbytes
@vrindex GNU.sparse.numbytes, extended header variable
@end table
The latter two variables repeat for each data block, so the overall
@end table
The latter two variables repeat for each data block, so the overall
-GNU.sparse.size=@var{size}
-GNU.sparse.numblocks=@var{numblocks}
+GNU.sparse.size=@var{size}
+GNU.sparse.numblocks=@var{numblocks}
repeat @var{numblocks} times
repeat @var{numblocks} times
- GNU.sparse.offset=@var{offset}
- GNU.sparse.numbytes=@var{numbytes}
+ GNU.sparse.offset=@var{offset}
+ GNU.sparse.numbytes=@var{numbytes}
end repeat
@end group
@end smallexample
end repeat
@end group
@end smallexample
@code{GNU.sparse.numbytes} are conflicting with the POSIX specs.
@item
@code{GNU.sparse.numbytes} are conflicting with the POSIX specs.
@item
-Attempting to extract such archives using a third-party @command{tar}s
-results in extraction of sparse files in @emph{compressed form}. If
+Attempting to extract such archives using a third-party's @command{tar}
+results in extraction of sparse files in @emph{condensed form}. If
the @command{tar} implementation in question does not support POSIX
format, it will also extract a file containing extension header
attributes. This file can be used to expand the file to its original
the @command{tar} implementation in question does not support POSIX
format, it will also extract a file containing extension header
attributes. This file can be used to expand the file to its original
@item GNU.sparse.map
@vrindex GNU.sparse.map, extended header variable
Map of non-null data chunks. It is a string consisting of
@item GNU.sparse.map
@vrindex GNU.sparse.map, extended header variable
Map of non-null data chunks. It is a string consisting of
-comma-separated values "@var{offset},@var{size}[,@var{offset-1},@var{size-1}...]"
+comma-separated values "@var{offset},@var{size}[,@var{offset-1},@var{size-1}...]"
@end table
To address the 2nd problem, the @code{name} field in @code{ustar}
@end table
To address the 2nd problem, the @code{name} field in @code{ustar}
The resulting @code{GNU.sparse.map} string can be @emph{very} long.
Although POSIX does not impose any limit on the length of a @code{x}
The resulting @code{GNU.sparse.map} string can be @emph{very} long.
Although POSIX does not impose any limit on the length of a @code{x}
-header variable, this possibly can confuse some tars.
+header variable, this possibly can confuse some @command{tar}s.
@node PAX 1
@appendixsubsec PAX Format, Version 1.0
@node PAX 1
@appendixsubsec PAX Format, Version 1.0
variable @code{GNU.sparse.realsize}.
The sparse map itself is stored in the file data block, preceding the actual
variable @code{GNU.sparse.realsize}.
The sparse map itself is stored in the file data block, preceding the actual
-file data. It consists of a series of octal numbers of arbitrary length, delimited
+file data. It consists of a series of octal numbers of arbitrary length, delimited
by newlines. The map is padded with nulls to the nearest block boundary.
The first number gives the number of entries in the map. Following are map entries,
each one consisting of two numbers giving the offset and size of the
data block it describes.
by newlines. The map is padded with nulls to the nearest block boundary.
The first number gives the number of entries in the map. Following are map entries,
each one consisting of two numbers giving the offset and size of the
data block it describes.
-The format is designed in such a way that non-posix aware tars and tars not
+The format is designed in such a way that non-posix aware @command{tar}s and @command{tar}s not
supporting @code{GNU.sparse.*} keywords will extract each sparse file
in its condensed form with the file map prepended and will place it
into a separate directory. Then, using a simple program it would be
possible to expand the file to its original form even without @GNUTAR{}.
@xref{Sparse Recovery}, for the detailed information on how to extract
sparse members without @GNUTAR{}.
supporting @code{GNU.sparse.*} keywords will extract each sparse file
in its condensed form with the file map prepended and will place it
into a separate directory. Then, using a simple program it would be
possible to expand the file to its original form even without @GNUTAR{}.
@xref{Sparse Recovery}, for the detailed information on how to extract
sparse members without @GNUTAR{}.
@cindex snapshot files, editing
@cindex snapshot files, fixing device numbers
Sometimes device numbers can change after upgrading your kernel
@cindex snapshot files, editing
@cindex snapshot files, fixing device numbers
Sometimes device numbers can change after upgrading your kernel
-version or recofiguring the harvare. Reportedly this is the case with
+version or reconfiguring the hardware. Reportedly this is the case with
some newer @i{Linux} kernels, when using @acronym{LVM}. In majority of
cases this change is unnoticed by the users. However, it influences
@command{tar} incremental backups: the device number is stored in tar
some newer @i{Linux} kernels, when using @acronym{LVM}. In majority of
cases this change is unnoticed by the users. However, it influences
@command{tar} incremental backups: the device number is stored in tar
device numbers in snapshot files. The utility, written by
Dustin J.@: Mitchell, is available from
@uref{http://www.gnu.org/@/software/@/tar/@/utils/@/tar-snapshot-edit.html,
device numbers in snapshot files. The utility, written by
Dustin J.@: Mitchell, is available from
@uref{http://www.gnu.org/@/software/@/tar/@/utils/@/tar-snapshot-edit.html,
- To obtain the device numbers used in the snapshot file, run
+ To obtain the device numbers used in the snapshot file, run
@smallexample
$ @kbd{tar-snapshot-edit @var{snapfile}}
@smallexample
$ @kbd{tar-snapshot-edit @var{snapfile}}
@noindent
where @var{snapfile} is the name of the snapshot file (you can supply as many
@noindent
where @var{snapfile} is the name of the snapshot file (you can supply as many
-files as you wish in a single command line ).
+files as you wish in a single command line).
To update all occurrences of the given device number in the file, use
@option{-r} option. It takes a single argument of the form
To update all occurrences of the given device number in the file, use
@option{-r} option. It takes a single argument of the form
from archives.
Copyright @copyright{} 1992, 1994, 1995, 1996, 1997, 1999, 2000, 2001,
from archives.
Copyright @copyright{} 1992, 1994, 1995, 1996, 1997, 1999, 2000, 2001,
-2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc.
+2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 Free Software Foundation, Inc.
@quotation
Permission is granted to copy, distribute and/or modify this document
@quotation
Permission is granted to copy, distribute and/or modify this document
The second chapter is a tutorial (@pxref{Tutorial}) which provides a
gentle introduction for people who are new to using @command{tar}. It is
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.
chapters to make sense. It moves from topic to topic in a logical,
progressive order, building on information already explained.
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
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
@node Tutorial
@chapter Tutorial Introduction to @command{tar}
@node Tutorial
@chapter Tutorial Introduction to @command{tar}
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. We will indicate those abbreviations
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. We will indicate those abbreviations
-appropriately to get you used to seeing them. (Note that the ``old
+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
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
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
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
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
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
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}.
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
@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
-(note the different font styles).
+lines (note the different font styles).
@end ifinfo
In the rest of the examples in this chapter, we will frequently use
@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
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
@node list
@section How to List Archives
@smallexample
tar: folk: Not found in archive
tar: jazz: Not found in archive
@smallexample
tar: folk: Not found in archive
tar: jazz: Not found in archive
@end smallexample
@noindent
@end smallexample
@noindent
@smallexample
$ @kbd{tar -tvf music.tar}
@smallexample
$ @kbd{tar -tvf music.tar}
practice/folk
practice/jazz
practice/folk
practice/jazz
@end smallexample
@FIXME{make sure the above works when going through the examples in
@end smallexample
@FIXME{make sure the above works when going through the examples in
different times during the history of @command{tar}. These styles will be
presented below, from the most recent to the oldest.
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
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
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
@section All @command{tar} Options
The coming manual sections contain an alphabetical listing of all
@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.
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
@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}
tape! @xref{delete}.
@opsummary{diff}
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
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
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.
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.
@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
@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
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
@opsummary{new-volume-script}
@item --new-volume-script
@opsummary{new-volume-script}
@item --new-volume-script
+(see @option{--info-script})
@opsummary{newer}
@item --newer=@var{date}
@opsummary{newer}
@item --newer=@var{date}
@smallexample
$ tar --show-defaults
@smallexample
$ tar --show-defaults
---format=gnu -f- -b20 --quoting-style=escape \
+--format=gnu -f- -b20 --quoting-style=escape
--rmt-command=/usr/libexec/rmt --rsh-command=/usr/bin/rsh
@end smallexample
--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.
+
@opsummary{show-omitted-dirs}
@item --show-omitted-dirs
@opsummary{show-omitted-dirs}
@item --show-omitted-dirs
@noindent
would extract this file to file @file{name}.
@noindent
would extract this file to file @file{name}.
-@opsummary{suffix}, summary
@item --suffix=@var{suffix}
Alters the suffix @command{tar} uses when backing up files from the default
@item --suffix=@var{suffix}
Alters the suffix @command{tar} uses when backing up files from the default
@smallexample
tar (GNU tar) @value{VERSION}
@smallexample
tar (GNU tar) @value{VERSION}
-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>.
+Copyright (C) 2010 Free Software Foundation, Inc.
+Copyright (C) 2010 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.
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}
@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}
@cindex Obtaining help
@cindex Listing all @command{tar} options
@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
@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
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
-@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
--format=gnu -f- -b20 --quoting-style=escape
--rmt-command=/etc/rmt --rsh-command=/usr/bin/rsh
@end group
@section Controlling Warning Messages
Sometimes, while performing the requested task, @GNUTAR{} notices
@section Controlling Warning Messages
Sometimes, while performing the requested task, @GNUTAR{} notices
-some conditions that are not exactly erros, but which the user
+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
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
@cindex @samp{door ignored}, warning message
@item file-ignored
@samp{%s: Unknown file type; file ignored}
@cindex @samp{door ignored}, warning message
@item file-ignored
@samp{%s: Unknown file type; file ignored}
-@samp{%s: socket ignored}
+@*@samp{%s: socket ignored}
@*@samp{%s: door ignored}
@kwindex file-unchanged
@cindex @samp{file is unchanged; not dumped}, warning message
@*@samp{%s: door ignored}
@kwindex file-unchanged
@cindex @samp{file is unchanged; not dumped}, warning message
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},
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
@samp{collection.tar} and @samp{music.tar}.
We will also use the archive files @samp{afiles.tar} and
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,
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
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
+@option{--keep-old-files} option, or the disk copy is newer than
the one in the archive and you invoke @command{tar} with
the one in the archive and you invoke @command{tar} with
-@option{--keep-newer-files} option}. Thus, only the most recently archived
+@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.
member will end up being extracted, as it will replace the one
extracted before it, and so on.
@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...
@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
@cindex Members, replacing with other members
@cindex Replacing members with other members
the one at the end will be newer and larger, since you added text before
updating it.
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.
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
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, @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
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
@end smallexample
@FIXME{Check if the above listing is actually produced after running
@end smallexample
@FIXME{Check if the above listing is actually produced after running
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 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, @xref{verify}.
@node create options
@section Options Used by @option{--create}
@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
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.
with @samp{/} or @samp{.}. In the latter case, the modification time
of that file will be used.
archives. For example:
@smallexample
archives. For example:
@smallexample
$ @kbd{tar -c -f archive.tar --owner=0 .}
$ @kbd{tar -c -f archive.tar --owner=0 .}
+@end smallexample
+
+@noindent
+or:
+
+@smallexample
$ @kbd{tar -c -f archive.tar --owner=root .}
$ @kbd{tar -c -f archive.tar --owner=root .}
@end smallexample
@item --group=@var{group}
@end smallexample
@item --group=@var{group}
directory timestamp will be offset again.
To correctly restore directory meta-information in such cases, use
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
@table @option
@opindex delay-directory-restore
Extract files and pipe their contents to the standard input of
@var{command}. When this option is used, instead of creating the
files specified, @command{tar} invokes @var{command} and pipes the
Extract files and pipe their contents to the standard input of
@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
+contents of the files to its standard output. The @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
extracted. Non-regular files (directories, etc.) are ignored when this
contain command line arguments. The program is executed via
@code{sh -c}. Notice, that @var{command} is executed once for each regular file
extracted. Non-regular files (directories, etc.) are ignored when this
@vrindex TAR_BLOCKING_FACTOR, to-command environment
@item TAR_BLOCKING_FACTOR
@vrindex TAR_BLOCKING_FACTOR, to-command environment
@item TAR_BLOCKING_FACTOR
-Current blocking factor (@pxref{Blocking}.
+Current blocking factor (@pxref{Blocking}).
@vrindex TAR_VOLUME, to-command environment
@item TAR_VOLUME
@vrindex TAR_VOLUME, to-command environment
@item TAR_VOLUME
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
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:
@smallexample
$ @kbd{(cd sourcedir; tar -cf - .) | (cd targetdir; tar -xf -)}
@smallexample
$ @kbd{(cd sourcedir; tar -cf - .) | (cd targetdir; tar -xf -)}
@end smallexample
@noindent
@end smallexample
@noindent
-The command also works using short option forms:
+The command also works using long option forms:
@smallexample
$ @kbd{(cd sourcedir; tar --create --file=- . ) \
| (cd targetdir; tar --extract --file=-)}
@smallexample
$ @kbd{(cd sourcedir; tar --create --file=- . ) \
| (cd targetdir; tar --extract --file=-)}
+@end smallexample
+
+@noindent
+or
+
+@smallexample
$ @kbd{tar --directory sourcedir --create --file=- . ) \
| tar --directory targetdir --extract --file=-}
@end smallexample
$ @kbd{tar --directory sourcedir --create --file=- . ) \
| tar --directory targetdir --extract --file=-}
@end smallexample
@anchor{device numbers}
@cindex Device numbers, using in incremental backups
Metadata stored in snapshot files include device numbers, which,
@anchor{device numbers}
@cindex Device numbers, using in incremental backups
Metadata stored in snapshot files include device numbers, which,
-obviously are supposed to be a non-volatile values. However, it turns
+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 @acronym{NFS} devices numbers over time. The solution implemented
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 @acronym{NFS} devices numbers over time. The solution implemented
-currently is to considers all @acronym{NFS} devices as being equal
+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.
when it comes to comparing directories; this is fairly gross, but
there does not seem to be a better way to go.
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
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, @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
@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}
@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
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
@GNUTAR{} comes with scripts you can use to do full
and level-one (actually, even level-two and so on) dumps. Using
(for @code{restore}). These should be accessible from the machine on
which the backup script is run.
(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.
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}.
@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
device. Their names are kept in the following variables:
@defvr {Backup variable} MT_BEGIN
-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.
@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
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
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
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:
The @option{--time} option determines when should the backup be
run. @var{Time} may take three forms:
-The dump must be run at @var{hh} hours
+The dump must be run at @var{hh} hours.
@file{backup-specs} (@pxref{General-Purpose Variables,BACKUP_DIRS}).
You may select the file systems (and/or files) to restore by
@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
line. For example, running
@smallexample
@table @option
@item -a
@itemx --all
@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}
@item -l @var{level}
@itemx --level=@var{level}
@end smallexample
@noindent
@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}
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
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
(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
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.
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.
more information.)
@smallexample
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
$ @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
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:
the common use of this feature is to change to another directory by
specifying @option{-C} option:
-@subsection @code{NUL} Terminated File Names
+@subsection @code{NUL}-Terminated File Names
@cindex File names, terminated by @code{NUL}
@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
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
@table @option
@xopindex{null, described}
@item --null
@table @option
@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}
terminate in a newline.
@xopindex{no-null, described}
@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
@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
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
The @option{--no-null} option can be used if you need to read both
$ @kbd{tar -c -v --null --files-from=long-files --file=big.tar}
@end smallexample
The @option{--no-null} option can be used if you need to read both
-zero-terminated and newline-terminated files on the same command line.
+@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
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 |
+$ @kbd{find . -size +800 -print0 |
tar -c -f big.tar --null -T - --no-null -T flist}
@end group
@end smallexample
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.
This example uses short options for typographic reasons, to avoid
very long lines.
-@GNUTAR is able to automatically detect null-terminated file lists, so
+@GNUTAR is able to automatically detect @code{NUL}-terminated file lists, so
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
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 -}
+$ @kbd{find . -size +800 -print0 | tar -c -f big.tar -T -}
tar: -: file name read contains nul character
@end group
@end smallexample
tar: -: file name read contains nul character
@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
@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 it,
+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
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
@var{regexp} and @var{replace} are described in detail in
@ref{The "s" Command, The "s" Command, The `s' Command, sed, GNU sed}.
@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 lieue of @samp{/}, the only requirement being
+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:
that it be used consistently throughout the expression. For example,
the following two expressions are equivalent:
-Use case-insensitive matching
+Use case-insensitive matching.
@item x
@var{regexp} is an @dfn{extended regular expression} (@pxref{Extended
@item x
@var{regexp} is an @dfn{extended regular expression} (@pxref{Extended
@end smallexample
This is definitely not desired. To avoid this, the @samp{S} flag
@end smallexample
This is definitely not desired. To avoid this, the @samp{S} flag
-are used, which excludes symbolic link targets from filename
+is used, which excludes symbolic link targets from filename
transformations. The result is:
@smallexample
transformations. The result is:
@smallexample
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
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}.
You can use the @option{--directory} option to make the archive
independent of the original name of the directory holding the files.
You can use the @option{--directory} option to make the archive
independent of the original name of the directory holding the files.
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
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},
@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.}.
If you use the @option{--absolute-names} (@option{-P}) option,
@command{tar} will do none of these transformations.
If you use the @option{--absolute-names} (@option{-P}) option,
@command{tar} will do none of these transformations.
Notice also, that there are several restrictions on operations on
compressed archives. First of all, compressed archives cannot be
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}))
+modified, i.e., you cannot update (@option{--update}, alias @option{-u})
them or delete (@option{--delete}) members from them or
them or delete (@option{--delete}) members from them or
-add (@option{--append} (@option{-r})) members to them. Likewise, you
+add (@option{--append}, alias @option{-r}) members to them. Likewise, you
cannot append another @command{tar} archive to a compressed archive using
cannot append another @command{tar} archive to a compressed archive using
-@option{--concatenate} (@option{-A})). Secondly, multi-volume
+@option{--concatenate} (@option{-A}). Secondly, multi-volume
archives cannot be compressed.
The following table summarizes compression options used by @GNUTAR{}.
archives cannot be compressed.
The following table summarizes compression options used by @GNUTAR{}.
@item --use-compress-program=@var{prog}
@itemx -I=@var{prog}
Use external compression program @var{prog}. Use this option if you
@item --use-compress-program=@var{prog}
@itemx -I=@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:
+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. 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.
First, when called without options, it should read data from standard
input, compress it and output it on standard output.
#! /bin/sh
case $1 in
-d) gpg --decrypt - | gzip -d -c;;
#! /bin/sh
case $1 in
-d) gpg --decrypt - | gzip -d -c;;
*) echo "Unknown option $1">&2; exit 1;;
esac
@end group
*) echo "Unknown option $1">&2; exit 1;;
esac
@end group
The numeric ids are @emph{always} saved into @command{tar} archives.
The identifying names are added at create time when provided by the
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.
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.
produces the following diagnostics:
@smallexample
produces the following diagnostics:
@smallexample
-$ tar -c -f ../archive.tar jeden
+$ tar -c -f ../archive.tar -l jeden
tar: Missing links to `jeden'.
@end smallexample
tar: Missing links to `jeden'.
@end smallexample
environment variable. If @var{TMPDIR} is not set, @command{tar}
uses @samp{/tmp}.
environment variable. If @var{TMPDIR} is not set, @command{tar}
uses @samp{/tmp}.
-@item exthdr.mtime=@var{value}
+@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.
This keyword defines the value of the @samp{mtime} field that
is written into the ustar header blocks for the global extended headers.
restore their missing files with an incompatible file extractor, or
vice versa.
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
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
(4.3-tahoe and later).
@command{tar}'s way of handling multiple hard links to a file can handle
(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}"
@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
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).
---rmt-command}, for detailed description of this option. @xref{Remote
Tape Server}, for the description of @command{rmt} command).
@end table
@node Remote Tape Server
@end table
@node Remote Tape Server
-@section The Remote Tape Server
+@section Remote Tape Server
@cindex remote tape drive
@pindex rmt
@cindex remote tape drive
@pindex rmt
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
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.
This means that the @option{--append}, @option{--concatenate}, and
@option{--delete} commands will not work on any other kind of file.
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
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.
@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}
@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
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
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
@cindex Exabyte blocking
@cindex DAT blocking
Moves tape position back @var{number} files.
@item rewind
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
@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.
@item status
Prints status information about the tape unit.
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
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
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
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
-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}
@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
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
@item y
Request @command{tar} to begin writing the next volume.
@end table
@item y
Request @command{tar} to begin writing the next volume.
@end table
@vrindex TAR_BLOCKING_FACTOR, info script environment variable
@item TAR_BLOCKING_FACTOR
@vrindex TAR_BLOCKING_FACTOR, info script environment variable
@item TAR_BLOCKING_FACTOR
-Current blocking factor (@pxref{Blocking}.
+Current blocking factor (@pxref{Blocking}).
@vrindex TAR_VOLUME, info script environment variable
@item TAR_VOLUME
@vrindex TAR_VOLUME, info script environment variable
@item TAR_VOLUME
@vrindex TAR_SUBCOMMAND, info script environment variable
@item TAR_SUBCOMMAND
@vrindex TAR_SUBCOMMAND, info script environment variable
@item TAR_SUBCOMMAND
-A 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
@xref{Operations}, for a complete list of subcommand options.
@vrindex TAR_FORMAT, info script environment variable
@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.
@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}.
reading an archive, it checks to make sure the label on the tape
matches the one you give. @xref{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
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
@end table
If you create an archive using both
@end table
If you create an archive using both
@group
$ @kbd{tar cfMV /dev/tape "Daily backup for `date +%Y-%m-%d`"}
$ @kbd{tar --create --file=/dev/tape --multi-volume \
@group
$ @kbd{tar cfMV /dev/tape "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
@end group
@end smallexample
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
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
The write protection device itself is usually an integral part of the
physical media, and can be a two position (write enabled/write
tar: Error exit delayed from previous errors
@end smallexample
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.
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.
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
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.
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.
timespec
unlinkdir
unlocked-io
timespec
unlinkdir
unlocked-io
utimens
version-etc-fsf
xalloc
utimens
version-etc-fsf
xalloc